Technote 1189

CONTENTS

Introduction

Disk Driver Basics

Driver Gestalt

Secrets of the Partition Map

Non-512 Byte Block Devices

Large Volume Support

How the ROM Loads SCSI and ATA Drivers

Loading FireWire Drivers

Chaining Drivers and Patch Partitions

Disk Drivers and the System Heap

PowerPC Native Disk Drivers

Installing and Removing Drivers and Drives

Close and Purge

File Exchange (né PC Exchange)

Private Control and Status Requests

Read-Verify Mode

Color Icons

Target Mode

Disk Driver Power Management

Summary

This Technote is both a summary and review of existing disk driver information and a description of disk driver features that until now have not been generally documented.

This Note is directed at developers of disk drivers and disk formatting utilities. There is also a section specifically aimed at application developers who need to operate on disks directly.

Introduction

The Mac OS disk driver architecture has not been comprehensively documented since Inside Macintosh II (1985). In the intervening years, disk technology has changed radically, from 400 KB floppy disks to FireWire, visiting two different SCSI Managers and four versions of ATA Manager on the way. Many of these technological changes have been accompanied by architectural changes for which the documentation is in obscure places, was not generally released, or was just never written.

The technote is an attempt to rectify that oversight. It serves both to bring together the existing documentation and to fill in the missing pieces. You can use this technote as either a reference, an introduction to writing disk drivers, or just to bring yourself up-to-date on the latest disk driver advances.

If you are new to Mac OS disk drivers, you should start with the Disk Driver Basics section. If you're already familiar with the basics of the Mac OS disk driver architecture, you may want to start with the two high-level summaries, one for disk driver writers and one for application developers.

Existing Information

The existing documentation for disk drivers is scattered through many different Apple documents, interface files, and code samples. The section classifies these references based on their usefulness.

Core References

These large works cover information that you will definitely need in your driver. Don't start a disk driver without being familiar with these works:

• Inside Macintosh: Devices, SCSI Manager is the core reference for the classic SCSI Manager programming interface, introduced with the Mac Plus. It also describes the Apple partition map format, used by all Macintosh computers since the Mac Plus.
• Inside Macintosh: Devices, SCSI Manager 4.3 is the core reference for the SCSI Manager 4.3 programming interface, introduced with the Quadra 840av. All SCSI drivers written today should use the SCSI Manager 4.3 programming interface.
• ATA Device Software for Macintosh Computers (previously known as the ATA Device Software Guide) is the core reference for the ATA Manager, which allows you to find and control ATA devices connected to the computer. The "ATA Driver Reference" chapter offers a useful summary of the Control and Status requests relevant to a modern Mac OS hard disk driver, although some of the information is inaccurate and has been updated in this document.
• ATA 0/1 Software Developers Guide is a supplement to the above, and describes the changes required to support device 0/1 (master/slave) on ATA buses.
• Inside Macintosh: Files describes the drive queue, a key data structure used by all disk drivers.
• Technote 1041, "Inside Macintosh: Files Errata" comprises corrections to the core Inside Macintosh: Files document.
• The Shared Device Access Protocol specification.
• DTS sample code RAM Disk implements the basic framework for a disk driver. Unfortunately, it does not demonstrate how to handle requests asynchronously, which is one of the trickiest things to get right in a disk driver.
• DTS sample code TradDriverLoaderLib shows how to correctly install a Mac OS driver 'DRVR'.
• DTS sample code SCSI Driver Example demonstrates a fully fledged SCSI driver that supports both classic SCSI Manager and SCSI Manager 4.3. It is a useful sample, although it has decayed a bit in the years since it was last updated (1994).
• DTS sample code ATA_Demo demonstrates how to read blocks from both ATA and ATAPI disks.
• "DriverGestalt.h" (from the latest Universal Interfaces) always contains the most up-to-date list of Driver Gestalt selectors.
• The MoreDisks module from the DTS sample code library MoreIsBetter contains a comprehensive list of all the currently defined disk driver Control and Status requests, and where to get more information on how to support them.

Additional Information

These smaller documents contain information that supplements the above in certain key areas.

• Technote 1098, "ATA Device Software Guide: Additions and Corrections" is the latest errata for the ATA Device Software for Macintosh Computers.
• Technote DV 17 Sony Driver: What your Sony Drives For You documents the Control and Status requests supported by Apple's standard floppy disk driver. This is a key reference for disk driver developers. Floppy disk driver writers should also read the "MFM Disk Device Driver" chapter of Apple Logic Board Design LPX-40 Developer Note (hardware developer note), which includes information on floppy disk Control and Status requests that is missing from DV 17.
• Technote DV 22, "CD-ROM Driver Calls" documents the Control and Status requests supported by Apple's standard CD-ROM driver. This is a key reference for CD-ROM driver developers.
• Technote 1104, "Interrupt-Safe Routines" answers the perennial question, can I do X at interrupt time?
• Technote 1067, "Traditional Device Drivers: Sync or Swim" addresses a common misconception of device driver writers.
• Technote 1040, "Write Cache Flushing: Techniques for Properly Handling System Shutdown" describes how disk drivers should handle system shutdown.
• Technote ME 09, "Coping with VM and Memory Mappings" is probably the best place for information on ensuring that your device driver is compatible with virtual memory.
• Technote 1094, "Virtual Memory Application Compatibility" contains a description of the Mac OS VM architecture as a whole, which is useful background material for device driver writers.
• Designing PCI Cards and Drivers for Power Macintosh Computers, pages 110 through 117, documents the Driver Gestalt mechanism and some new Control requests. This technote provides clarifications and corrections on Driver Gestalt and the mechanism used to boot from a partition. In addition, the File Exchange section of this technote completely replaces the PC Exchange description in the book.
• Guide to the File System Manager contains useful background information about how FSM interacts with disk drivers; however, the specific recommendations for driver writers are covered in the File Exchange section of this technote.
• DTS Q&A OPS 22, "Notification Manager Reinitialized During Boot" is an important tidbit for disk driver developers.
• DTS Q&A DV 34, "Secondary Interrupts on the Page Fault Path" describes the dangers of using secondary interrupts in software that must service page faults. While the Q&A was written for SIM developers, its warning is also important for other page fault path software, such as disk drivers. Disk drivers must not use secondary interrupts (or, for that matter, deferred tasks) on the page fault path.
• Data Structure to Aid Security and Recovery Software, David Shayer and Marvin Carlberg, 1991
• The InterruptSafeDebug module of the DTS sample code library MoreIsBetter can be useful when tracking down nasty crashing problems in a device driver, especially those that happen early at startup time.

Obsolete

These documents, as they pertain to disk drivers, are considered obsolete. This list is provided for completeness only. You should read the recommended material instead.

• Inside Macintosh II, "The Disk Driver", page 211 through 219, documents the basic interface to a disk driver, include the kEject (7) Control request, the kSetTagBuffer (8) Control request, and the kDriveStatus (8) Status request.
• Inside Macintosh IV, "The Disk Driver", page 223 through 224, documents the kVerify (5), kFormat (6), kTrackCache (9), and kDriveIcon (21) Control requests.
• Inside Macintosh IV, "The SCSI Manager", page 292 through 293 describes the original partitioning format used on the Mac Plus and goes on to say, "Since the driver is called to install itself, it must contain code to set up its own entry in the unit table and to call its own Open routine. An example of how to do this can be obtained from Developer Technical Support." This example was part of the "SCSI Driver Developer Kit". All of the information in the kit is available elsewhere. The specific sample code referenced by the book evolved into SCSI Driver Example.
• Inside Macintosh V, "The Disk Driver", page 470 through 471, documents the kDriveIcon (21), kMediaIcon (22), and kDriveInfo (23) Control requests.
• Technote DV 2, "_AddDrive, _DrvrInstall, and _DrvrRemove" documented the AddDrive, DriverInstall, and DriverRemove system routines. This technote is now obsolete. AddDrive is documented in Inside Macintosh: Files, and DriverInstall, and DriverRemove are covered by Inside Macintosh: Devices, along with DriverInstallReserveMem. Moreover, developers of 68K drivers should use TradDriverLoaderLib to install their drivers.
• Technote DV 12, "Our Checksum Bounced" documents a misfeature of the code used by the ROM to checksum disk drivers. The technote is now obsolete. The ROM checksum behavior is described in Inside Macintosh: Devices and this technote describes the checksum algorithm itself.
• Technote DV 13, "_PBClose the Barn Door" still contains valid advice for general device driver writers, although this technote deals with this topic as it applies to disk drivers.
• Technote DV 18, "CD-ROM Notes (Most Excellent)" contains some interesting historical information about CD-ROM devices, although much of the information is now obsolete or covered elsewhere.
• Power Macintosh 9500 Computers (hardware developer note) describes many aspects of the large volume support (greater than 4 GB support) introduced with that machine. The large volume support aspects of that developer note are now obsolete. This technote discusses large volume support as it applies to disk drivers. DTS Q&As FL 07 and FL 08 discuss large volume support from the application perspective.
• The following documents were never released generally. Their developer-oriented content has been rolled into this technote.
  • "Chainable Drivers and Patches"
  • "Ruby Slipper Lite ERS" (large volume support)
  • "Bootable CD Developer Kit (Software Developer Note)"
  • "PC Exchange and Large Volume Drivers"

Checklist for Disk Driver Writers

All of the above is probably overwhelming, so here is a summary of the most important steps to take to improve the reliability and compatibility of your disk driver:

• If you do nothing else, you should support Driver Gestalt.
• You should support the partition map entry features documented in Secrets of the Partition Map. Specifically, you should ensure that your driver is checksummed, supports booting from a partition, and write your driver signature to the pmPad field.
• Your driver should support large volumes, including booting from large volumes on machines without large volume support in the ROM by means of the 'ruby' patch.
• You should follow the rules when installing and removing your driver and its drive queue elements. You should also support close to allow other developers to remove your driver cleanly.
• If your driver uses SCSI Manager 4.3 or ATA Manager, it must register itself with the manager. The documentation for each manager describes how this is done. If you're using SCSI Manager 4.3, use SCSICreateRefNumXref. If you're using ATA Manager, use kATAMgrDriveRegister.
• You should support the File Exchange interface. This will allow foreign file systems to access your disks without any skullduggery.
• You should check that your private Control and Status requests follow the rules, both with respect to Driver Gestalt and virtual memory. This is harder than you might think.
• You should support read-verify mode. This technote explains how to do it easily.
• You may want to support target mode in your ATA driver.
• You may want to support color icons. Woo hoo!

For Application Writers

The purpose of a disk driver is to support a generic interface for accessing block devices. The primary client of this interface is the File Manager, although it can be used by other programs. If you're writing a foreign file system, or just an application that needs something beyond the standard File Manager programming interface, parts of this technote may be of interest to you.

• If you need to interrogate a driver about its capabilities, you should read the section Driver Gestalt for Applications.
• If you need to read arbitrary blocks on a volume, you should read the discussion of the XIOParam block for applications, along with the accompanying hints and tips.
• If you need to read arbitrary blocks outside of a volume -- for example, the partition map, or a non-Mac OS partition -- you should investigate the File Exchange section of this technote, especially the section on using the File Exchange interface.
• If you need to verify that you have written data to the disk correctly, you should check out the read-verify mode section which describes the easiest way to do this. [Hint: Think "MoreFiles"!]
• If you need to get color icons for a drive, you can now call the disk driver to get them -- although you should probably just call Icon Services instead.

In addition, if you're writing a disk formatting utility, this technote contain invaluable information on the partition map, chaining drivers, patch partitions, and "hostile" takeovers.

Disk Driver Basics

Mac OS communicates with attached devices through device drivers, which are software plug-ins that conform to a well-defined structure. The Device Manager is the original system component used to install, find, manage, and communicate with device drivers. It exports routines that can be called by higher level system software, and by applications. Most of these routines translate directly into requests to the underlying device driver.

In order to identify different drivers, the Device Manager assigns each installed driver a unique negative number, referred to as a driver reference number. When calling the Device Manager, clients pass a driver reference number to tell it which driver they are dealing with.

For a block device to be available to the system, it must have a disk driver. This is either in the ROM (for the built-in floppy drive), or loaded at system startup from a special partition on the disk (SCSI, ATA, and FireWire devices), or loaded from a system extension (USB and FireWire devices). In addition, a disk driver can be loaded when a device is plugged in by either an I/O family expert (ATA, USB, and FireWire), or by a special utility program (SCSI). Finally, software can install a disk driver for a virtual block device which has no obvious physical presence, such as a RAM disk or disk image. Regardless of how they are installed, all disk drivers roughly follow the same rules.

It is important to note the difference between a disk and a device. A block device is the entity which reads and writes data on a disk. A disk is the medium which actually stores the data. This distinction is unimportant for fixed disk devices (such as hard disks), but is critical for removable disk devices (such as floppy drives and removable cartridge disk devices).

Mac OS always directs block I/O to a software entity known as a drive. Each disk driver creates one or more drives and puts them in a system structure called the drive queue. Each drive queue element represents a drive, and contains both the driver reference number and the drive number. The drive number is a positive number that uniquely identifies the drive; it is assigned when the drive is added to the drive queue.

A drive does not necessarily correspond directly to a given physical device. Rather, the driver decides which drives to create for the device it controls. In some cases, there is one drive per physical device. For example, the built-in floppy disk driver creates a drive for each attached floppy disk device. However, it is also common for a driver to create multiple drives for a single device. For example, the driver for a partitioned hard disk device creates a drive for each file system partition on the disk.

When the system performs I/O to a drive, it supplies the driver reference number of the device driver and the drive number of a drive created by that driver. The Device Manager uses the driver reference number to find the device driver and call its entry point. The device driver then uses the drive number to determine which drive is the target of the I/O request.

All drive I/O is done is terms of 512-byte logical blocks. Therefore, all transfers must start at multiple of 512 bytes and be a multiple of 512 bytes long. This is regardless of the underlying device's block size.

File Manager and Drives

To allow the flexibility of storage required by the user interface (a hierarchy of folders and files), Mac OS implements another layer of abstraction, known as the File Manager, on top of the Device Manager and the drive queue.

A file system is a mechanism for storing fine-grained data (files) and meta-data (folders, Finders attributes, and so on) on a drive. The file system defines the way this data is stored and the rules for manipulating it. The File Manager includes built-in support for two file systems (HFS and HFS Plus) and a plug-in architecture (File System Manager) for others (AppleShare, DOS FAT, ProDOS , UDF, and third-party FSM plug-ins).

The File Manager exports a programming interface defined in terms of volumes, which contain directories, files, and meta-data. A volume is an instance of a file system on a drive. Each volume is uniquely identified by a negative volume reference number, which is stored, along with other data to operate the volume, in a volume control block (VCB) that is linked into the system VCB queue. The VCB also contains the drive number and the driver reference number of the drive on which the volume is mounted.

The process of making the contents of a drive available via the File Manager is called mounting a volume. When the File Manager attempts to mount a volume on a drive, it calls each of the file systems in turn to determine which one understands the logical format of the data on the disk in the drive. It then creates a VCB for that file system on that drive.

The File Manager takes requests to operate on the volume and passes them to the appropriate plug-in file system, which reduces them to basic block operations and passes them to the drive via the Device Manager (using the drive number and driver reference number stored in the VCB). As far as the file system is concerned, the drive is its own logical disk, even though it may only represent a small part of the real disk.

A drive can exist without having a volume mounted on it. This happens, for example, if the data format on the drive is incomprehensible to the installed file systems, or the volume on the drive has been unmounted. You can still access the data on a drive that has no volume mounted on it, but only via the Device Manager interface.

Terminology

In any technical document, it is very important to get your terminology straight. This is especially important when talking about disk drivers, where much of the terminology has been extended over the long, confusing history of the Mac OS block storage architecture. This technote uses the following terms throughout.

disk driver

A software plug-in that implements a hardware abstraction layer for block devices, like hard disks, floppy drives, and CD-ROM drives. In Mac OS, a disk driver must be a Device Manager driver (either a 68K driver or a native driver).

68K driver

A disk driver implemented using the traditional 68K driver architecture, as documented in Inside Macintosh: Devices. A 68K driver is commonly stored in a resource of type 'DRVR' or in a driver partition.

native driver

A disk driver implemented using the native driver model, introduced with the first generation of PCI Power Macintosh computers and documented in Designing PCI Cards and Drivers for Power Macintosh Computers. A native driver is commonly stored in a file of type 'ndrv', although native drivers have started appearing in driver partitions as well.

driver reference number

An SInt16 that uniquely identifies a Device Manager driver to the system. Driver reference numbers are not persistent -- they are assigned when the driver is added to the unit table -- but some driver reference numbers are assigned to certain well-known drivers. Driver reference numbers occupy the same "name space" as file reference numbers (which identify an open file). Driver reference numbers are always negative, while file reference numbers are always positive. Zero is an invalid driver reference number and an invalid file reference number.

unit table

A Device Manager data structure that lists the installed device drivers (both 68K and native).

block device

A block-oriented storage device.

real block device

A block device that has some obvious physical presence, such as a floppy drive or a SCSI hard disk device.

virtual block device

A block device this has no obvious physical presence, such as a RAM disk, a disk image, or a network block device.

device

Some hardware attached to the computer. In this context of this technote, this typically means a block device although, in some places, the term may be used for any type of device.

disk

The actual physical media which holds data. A disk is made up of blocks, each of which holds a fixed number of bytes (typically 512). A disk is distinct from a block device because, in the case of removable disk devices, the user can insert one of many different disks into the device.

disc

A synonym for "disk" that is only used in the context of CD or DVD discs (where the disk is actually a disc).

media

See disk.

drive

A Mac OS software construct used to represent a block storage entity. A volume is always mounted on a drive. There may be multiple drives corresponding to a single disk. Exception: some removable disk devices have been historically known as drives (for example, floppy drive, CD-ROM drive). This technote continues to use "drive" in these contexts, rather than the more cumbersome "floppy disk device." However, if the word "drive" appears unqualified, it always refers to the primary definition.

drive queue

A OS queue which contains all the drive queue elements known to the system. You can get the head of the drive queue using the routine GetDrvQHdr. See Inside Macintosh: Files for more details of the drive queue and its elements.

drive queue element

The specific data structure used to represent a drive. A drive queue element is a structure of type DrvQEl allocated in the system heap and placed in the drive queue.

drive number

An SInt16 which uniquely identifies a drive. Drive numbers are not persistent; they are assigned when the drive is added to the drive queue. Drive numbers occupy the same "name space" as volume reference numbers. Drive numbers are always positive, while volume reference numbers are always negative.

partition

A disk may be divided into a set of contiguous blocks, each known as a partition. Partitions are typically either file system partitions (which hold file system data) or meta-data partitions (which hold information about the disk, such as the partition map or the disk's device driver). Not all disks are partitioned, although a disk must be partitioned to support booting (except for floppy disks, because the driver for the built-in floppy disk drive is in the ROM).

partition map

A data structure, typically at the beginning of the disk, which describes the partitions on the disk. Most Mac OS disks are partitioned using the Apple partition map format, described in Secrets of the Partition Map.

partition map entry

The Apple partition map describes each partition on the disk using a partition map entry data structure (of type Partition).

startup partition

The partition which the user has designated as the one from which they prefer to boot the system, or the partition from which the system booted.

driver partition

A partition which contains a disk driver.

file system partition

A partition which contains file system data.

meta-data partition

A partition which holds information about the disk, such as the partition map or the disk's device driver.

partition-based driver

A driver that is loaded from a partition.

file system-based driver

A driver that is loaded from a file in the file system, typically in the Extensions folder.

disk-based driver

Either a partition-based driver or a file system-based driver. This term is ambiguous and to be avoided.

ghost partitioning

A system used on non-512 byte block devices where partition map entries appear at both 512-byte boundaries and device block boundaries so that they can be seen by software using either physical or device blocks.

I/O family

A component of the Mac OS I/O subsystem that is responsible for a particular category of devices. A driver can work within multiple I/O families. Each family requires certain attributes of the driver (for example, how it is packaged and the programming interface it provides to upper layer software) and provides services for the driver. For example, a FireWire disk driver must be packaged as a native driver which responds to the standard disk driver programming interface, and FireWire provides services to the disk driver, such as SBP-2 utility routines.

I/O family expert

A component of an I/O family that seeks out devices of a particular type and registers them with the I/O family.

volume

A File Manager software construct that represents a single, user-visible storage device. Each volume appears as a icon on the desktop. Each volume is mounted on a drive, so if the disk has multiple file system partitions it will also have multiple drives and hence multiple volumes.

volume reference number

An SInt16 which uniquely identifies a volume. Volume reference numbers are not persistent; they are assigned when the volume is mounted. Volume reference numbers occupy the same 'name space' as drive numbers. Drive numbers are always positive, while volume reference numbers are always negative.

refNum

This contraction of "reference number" is ambiguous and is not used in this document. In other documents, it commonly means either a driver reference number or a file reference number, depending on context.

vRefNum

A contraction of volume reference number.

logical blocks

The block numbering scheme used to access blocks on a drive. Each logical block contains 512 bytes and the first block accessible through the drive is block 0. See Block Translation for details.

physical blocks

The block numbering scheme used to access blocks on a disk. You can derive a physical block number from a logical block number by adding to it the start block number of the partition. If the disk is not partitioned, logical blocks and physical blocks are identical. Each physical block contains 512 bytes. See Block Translation for details.

device blocks

The actual block numbering scheme used by the device hardware to access data on the disk. Device blocks are not necessarily 512 bytes big, and the device driver is responsible for blocking and deblocking to present the illusion of 512-byte physical blocks to the system. See Block Translation for details.

blocks

When used without qualification in this technote, blocks means logical blocks.

sectors

Depending on context, this can either mean device blocks (for a floppy drive), physical blocks (for a hard disk device), or logical blocks (in a volume format specification). To avoid confusion, this technote avoids the term "sector" in favor of its more specific synonyms.

chaining driver

A driver loaded from a partition which performs some action and then loads the next driver in the driver chain. The most common chaining driver is Apple's patch driver.

driver chain

A sequence of drivers, each in its own driver partition, that can all be loaded for a particular expansion bus type (for example, SCSI or ATA). Each driver chain consists of one or more chaining drivers and a real driver for the disk. A disk may contain more than one driver chain if it can be accessed through more than one expansion bus type.

patch driver

A chaining driver which applies the patches from a patch partition and then chains to the next driver.

patch partition

A meta-data partition containing patches that must be applied to the system before it can boot. The patches in the patch partition are applied by the patch driver before it chains to the real disk driver.

target mode

PowerBook computers can be placed in target mode, where the PowerBook's internal hard disk device is accessible as a hard disk device to other computers on an expansion bus (typically SCSI).

SCSI disk mode

See target mode.

request

When the Device Manager calls a driver entry point (Open, Close, Prime, Control, or Status for a 68K driver, DoDriverIO for native drivers), it passes the address of a parameter block which describes the requested operation. This is known as a request. A request is different from a simple function call in that the driver may return from this initial call without completing the request. Specifically, for queued requests, the request is not complete until the driver explicitly tells the system so (by calling IODone for 68K drivers, or by calling IOCommandIsComplete for native drivers).

queued request

Synchronous and asynchronous requests are collectively known as queued requests. This is because they are queued in the driver's queue (on the dCtlQHdr) and the driver is marked as busy while the request is being processed.

immediate request

Immediate requests are distinct from queued requests in that they are not placed in the driver's queue and do not mark the driver as busy.

Driver Gestalt

All disk drivers should support Driver Gestalt. Driver Gestalt is a mechanism whereby the system can query your driver to determine whether it supports advanced driver features. In many ways it is similar to the Mac OS Gestalt Manager, except that the system is querying your driver, not the other way around.

Your driver should support Driver Gestalt. If you don't support Driver Gestalt, the system is in the dark as to which advanced driver features your driver supports.

Driver Gestalt Reference

The basic reference for Driver Gestalt is Designing PCI Cards and Drivers for Power Macintosh Computers, specifically the "Driver Gestalt" section starting on page 106. However, Driver Gestalt is useful even on non-PCI computers. Your driver must support Driver Gestalt regardless of what computer or OS version it is running on.

Designing PCI Cards and Drivers for Power Macintosh Computers does not document all of the selectors associated with Driver Gestalt. The only official, up-to-date list of Driver Gestalt selectors is the "DriverGestalt.h" header file, provided as part of Universal Interfaces. When Apple defines a new Driver Gestalt selector, we add the selector to "DriverGestalt.h", along with comments that describe how to implement it.

In the event of a conflict between the written documentation and "DriverGestalt.h", "DriverGestalt.h" is correct and the written documentation is wrong. For example, Designing PCI Cards and Drivers for Power Macintosh Computers describes the response of the 'purg' selector as a Boolean (page 111), whereas "DriverGestalt.h" correctly describes the response to be of type DriverGestaltPurgeResponse.

Driver Gestalt Guarantees

By saying that it supports Driver Gestalt, your driver guarantees certain things to the system, including:

1. Your driver will return controlErr in response to a Control request with an unrecognized csCode.
2. Your driver will return statusErr in response to a Status request with an unrecognized csCode.
3. Your driver will return controlErr in response to a Driver Configure request with an unrecognized selector.
4. Your driver will return statusErr in response to a Driver Gestalt request with an unrecognized selector.
5. Your driver will not use any csCodes below 128 for private Control or Status requests.

Items 3 and 4 in the list above are not documented clearly in Designing PCI Cards and Drivers for Power Macintosh Computers, although they are implemented by all Apple drivers and are clearly shown in the various Driver Gestalt samples. This technote serves to officially document these two additional requirements.

Driver Gestalt for Applications

Probably the best way to understand how to issue Driver Gestalt queries from an application is to look at some sample code. "Driver Gestalt Demo" is a simple sample that shows how to issue a few queries. "DriverGestaltExplorer" is a more comprehensive sample, which is also useful as a simple test and investigation tool. Both samples are available as DTS sample code.

Summary of Driver Gestalt

All disk drivers should support Driver Gestalt.

Secrets of the Partition Map

A number of features have been added to the Apple partition map since it was documented in Inside Macintosh: Devices. This section describes those features in detail.

Partition Field Relevance

The description of the Partition data type in Inside Macintosh: Devices does not explicitly call out that some fields of the data structure are only relevant for driver partitions (those whose partition name contains "Apple" and "Driver"). Specifically, the fields from pmLgBootStart through to pmProcessor are only relevant for driver partitions. Non-driver partitions should set these fields to zero.

pmParType Possibilities

Inside Macintosh: Devices documents the well known values for the pmParType field of the partition map entry, namely "Apple_partition_map", "Apple_Driver", "Apple_Driver43", "Apple_MFS", "Apple_HFS", "Apple_Unix_SVR2", "Apple_PRODOS", "Apple_Free", and "Apple_Scratch". This technote describes a number of additional partition types.

• "Apple_Driver_ATA" -- Holds the device driver for an ATA device.
• "Apple_Driver_ATAPI" -- Holds the device driver for an ATAPI device. When it discovers a device on an ATA bus, the ATA Manager identifies whether a device is ATA or ATAPI and automatically loads the corresponding driver.
• "Apple_Driver43_CD" -- A SCSI CD-ROM driver suitable for booting.
• "Apple_FWDriver" -- Holds a FireWire driver for the device. See Loading FireWire Drivers for details.
• "Apple_Void" -- A dummy partition map entry, used to pad out a partition map to ensure the correct alignment of partition map entries in a bootable CD-ROM.
• "Apple_Patches" -- Holds a patch partition. The patch partition architecture is described in Chaining Drivers and Patch Partitions.

pmPartStatus Revealed

Inside Macintosh: Devices says that the pmPartStatus field of the Partition data structure is only used by A/UX, bits 0 through 7 having a defined meaning and all others being reserved. This is no longer true.

The following flags are defined in pmPartStatus field of the Partition structure. All bits not defined here are reserved (you should initialize them to 0 and ignore their value).

enum {
    kPartitionAUXIsValid                        = 0x00000001,
    kPartitionAUXIsAllocated                    = 0x00000002,
    kPartitionAUXIsInUse                        = 0x00000004,
    kPartitionAUXIsBootValid                    = 0x00000008,
    kPartitionAUXIsReadable                     = 0x00000010,
    kPartitionAUXIsWriteable                    = 0x00000020,
    kPartitionAUXIsBootCodePositionIndependent  = 0x00000040,
     kPartitionIsWriteable                       = 0x00000020,
    kPartitionIsMountedAtStartup                = 0x40000000,
    kPartitionIsStartup                         = 0x80000000,
     kPartitionIsChainCompatible                 = 0x00000100,
    kPartitionIsRealDeviceDriver                = 0x00000200,
    kPartitionCanChainToNext                    = 0x00000400,
};

Bits 0 through 4 and 6 are still defined as documented in Inside Macintosh: Devices. A Mac OS formatting utility should always set these bit to 1 for file system partitions and clear them for other partition types.

The second group of bits is used by Apple Mac OS disk drivers to hold information about file system partitions.

kPartitionIsWriteable

This bit indicates whether the partition is writeable (1) or write-protected (0). If the bit is clear and your driver creates a drive queue element to represent this partition, it should mark the drive queue element as write-protected. Note that mask has the same value (and the same semantics) as kPartitionAUXIsWriteable.

kPartitionIsMountedAtStartup

This bit indicates whether the partition is mounted at system startup (1) or not (0). If your driver would otherwise create a drive queue element to represent this partition at system startup and this bit is clear, it should not create the drive.

kPartitionIsStartup

This bit indicates whether this is the startup partition (1) or not (0). This bit must be set for at most one partition. See A Partition of Your Imagination below.

The third group of bits provides information about driver partitions. You may need to read Chaining Drivers and Patch Partitions to understand these descriptions.

kPartitionIsChainCompatible

The driver in this partition supports being loaded by a chaining driver.

kPartitionIsRealDeviceDriver

This partition contains a driver that actually knows how to drive the device. Contrast this with the patch driver, which is chain compatible, but which can only load patches and then chain to the next driver; it does not actually contain a disk driver.

kPartitionCanChainToNext

This partition contains a driver that can chain to another driver. Typically, all drivers in the chain must have this bit set, except the last one where it is clear.

Partition Attributes

There are a number of Control and Status requests that modify the attributes of a partition. A disk driver must support these requests as described below. A formatting application can use these requests to modify partition attributes.

Setting the Startup Partition

In response to this request, your disk driver must set the partition described by ioVRefNum and csParam[0..3] as the startup partition. Typically this involves setting kPartitionIsStartup in pmPartStatus, which in turn causes your disk driver to place the drive queue element for this partition first in the drive queue at system startup.

Determining Whether a Partition is the Startup Partition

In response to this request, your disk driver must set csParam[0] to indicate whether the partition described by ioVRefNum and csParam[0..3] is the startup partition. Typically this involves testing kPartitionIsStartup in pmPartStatus.

The request returns the status that is currently recorded in the partition map, not whether the system actually started from this partition.

Specifying That a Partition Should Be Mounted at Startup

In response to this request, your disk driver must set the partition described by ioVRefNum and csParam[0..3] to be mounted at startup. Typically this involves setting kPartitionIsMountedAtStartup in pmPartStatus, which in turn causes your disk driver to place a drive queue element for this partition in the drive queue at system startup.

This request modifies the partition map, and hence only takes effect the next time the system is started. It does not affect the state of any volume currently mounted on the partition.

Specifying That a Partition Should Not Be Mounted at Startup

In response to this request, your disk driver must set the partition described by ioVRefNum and csParam[0..3] to not be mounted at startup. Typically this involves clearing kPartitionIsMountedAtStartup in pmPartStatus, which in turn causes your disk driver to not place a drive queue element for this partition in the drive queue at system startup.

This request modifies the partition map and hence only takes effect the next time the system is started. It does not affect the state of any volume currently mounted on the partition.

Determining Whether a Partition is to be Mounted

In response to this request, your disk driver must set csParam[0] to indicate whether the partition described by ioVRefNum and csParam[0..3] is to be mounted at system startup. Typically this involves testing kPartitionIsMountedAtStartup in pmPartStatus.

The request returns the status that is currently recorded in the partition map, not whether the partition was actually mounted at startup.

Mounting a Partition Immediately

In response to this request, your disk driver must create a drive queue element for the partition described by ioVRefNum and csParam[0..3] (if it doesn't already have one) and post a "disk inserted" event for it. It must do this regardless of the state of the kPartitionIsMountedAtStartup bit in the partition's pmPartStatus; however, the kPartitionIsWriteable bit still controls whether the drive is writeable.

If there is already a volume mounted on the partition, the system will ignore the "extra disk inserted" event this request generates.

Locking a Partition

In response to this request, your disk driver must lock the partition described by ioVRefNum and csParam[0..3]. Typically this involves:

• clearing kPartitionIsWriteable in pmPartStatus, which in turn causes your disk driver to create a read-only drive queue element for this partition at system startup, and
• making the drive queue element associated with this partition read-only. A read-only drive queue element has bit 7 of the writeProt field of the drive queue element set, as described in Inside Macintosh: Files, page 2-85.

Unlocking a Partition

In response to this request, your disk driver must unlock the partition described by ioVRefNum and csParam[0..3]. Typically this involves:

• setting kPartitionIsWriteable in pmPartStatus, which in turn causes your disk driver to create a read/write drive queue element for this partition at system startup, and
• making the drive queue element associated with this partition read/write.

Determining Whether a Partition is Locked

In response to this request, your disk driver must set csParam[0] to indicate whether the partition described by ioVRefNum and csParam[0..3] is locked. Typically this involves testing kPartitionIsWriteable in pmPartStatus.

The request returns the status that is currently recorded in the partition map, not whether the partition was actually locked at startup. You can determine whether a drive is currently write-protected by looking at bit 7 of the writeProt field of the drive queue element, as described in Inside Macintosh: Files, page 2-85.

pmPad Pearls

A previously undocumented feature of the Partition structure is the use of the pmPad field. The first four bytes of this field is a driver signature, a Mac OS four- character code that uniquely identifies the driver. Developers must fill out this field with either a registered creator code (which is strongly recommended) or zero. Drivers that use a registered creator code in this driver signature field may then use the remainder of pmPad to hold driver-specific configuration parameters.

Apple currently uses the following driver signatures:

enum {
    kPatchDriverSignature   = 'ptDR',
    kSCSIDriverSignature    = 0x00010600,
    kATADriverSignature     = 'wiki',
    kSCSICDDriverSignature  = 'CDvr',
    kATAPIDriverSignature   = 'ATPI',
    kDriveSetupHFSSignature = 'DSU1'
};

The values have the following meaning:

kPatchDriverSignature

The Apple patch driver.

kSCSIDriverSignature

The Apple SCSI hard disk driver. [The significance of this value has been lost in the mists of time.]

kATADriverSignature

The Apple ATA hard disk driver.

kSCSICDDriverSignature

The Apple SCSI CD-ROM driver.

kATAPIDriverSignature

The Apple ATAPI CD-ROM driver.

kDriveSetupHFSSignature

Drive Setup sets the first four bytes of the pmPad field of "Apple_HFS" partitions to this value. While this is not, in the strictest sense, a driver signature, it is documented here for completeness.

Remember that your disk driver should use its own driver signature; do not use these values for your own driver.

New Driver Types

Inside Macintosh: Devices describes how a Mac OS driver is tagged by having ddType set to 1 in the driver descriptor map (DDM). There is a constant for this, sbMac, defined in "SCSI.h". However, there are other useful constants for this field.

enum {
    kDriverTypeMacSCSI          = 0x0001,
    kDriverTypeMacATA           = 0x0701,
    kDriverTypeMacSCSIChained   = 0xFFFF,
    kDriverTypeMacATAChained    = 0xF8FF
};

The following constants are defined for the ddType field of the DDM:

kDriverTypeMacSCSI

This is a Mac OS SCSI driver, equivalent to sbMac. Typically this is only used for the first driver (the patch driver) in a SCSI driver chain.

kDriverTypeMacATA

This is a Mac OS ATA driver. Typically this is only used for the first driver (the patch driver) in an ATA driver chain.

kDriverTypeMacSCSIChained

This is a chained Mac OS SCSI driver. This is used for the second and subsequent drivers in a driver chain.

kDriverTypeMacATAChained

This is a chained Mac OS ATA driver. This is used for the second and subsequent drivers in a driver chain.

The driver type for a chained driver is always the two's complement of the driver type for the patch driver. For more information about this relationship, see Chaining Drivers and Patch Partitions.

Driver Checksums

Inside Macintosh, Volume V (page 580) contains an assembly language description of the checksum algorithm used for the pmBootCksum field of the partition map, but this algorithm was somehow dropped from Inside Macintosh: Devices. As it is now quite difficult to obtain copies of Inside Macintosh, Volume V, the algorithm is included below.

; Inputs:
;   a0.l -> pointer to driver code
;   d1.w -> length of driver code in bytes
; Outputs:
;   d0.w -> driver checksum
                   DoCksum
        moveq.l     #0,d0       ; initialize sum register
        moveq.l     #0,d7       ; zero extended byte
        bra.s       CkDecr      ; handle 0 bytes
CkLoop
        move.b      (a0)+,d7    ; get a byte
        add.w       d7,d0       ; add to checksum
        rol.w       #1,d0       ; and rotate
CkDecr
        dbra        d1,CkLoop   ; next byte
        tst.w       d0          ; convert a checksum of 0
        bne.s       @1          ; into $FFFF
        subq.w      #1,d0       ;
@1

The following is a C equivalent.

static UInt32 ChecksumDriver(void *start, UInt16 bytesToSum)
{
    UInt8  *cursor;
    UInt16 result;
    
    cursor = (UInt8 *) start;
    result = 0;
    
    while ( bytesToSum != 0 ) {
        result = result + *cursor;
        result = ((result <<  1) & 0x0FFFE) |
                 ((result >> 15) & 0x00001);
        cursor += 1;
        bytesToSum -= 1;
    } 
    if (result == 0) {
        result = 0x0FFFF;
    }
    return result;
}

One minor mystery of the pmBootCksum field is that the field is 32 bits wide but the checksum algorithm only calculates a 16-bit value. The checksum is always stored in the least significant 16 bits of pmBootCksum and the most significant bits are always set to zero.

Inside Macintosh, Volume V also states that driver checksumming is only done for if the first four bytes of the driver's partition map entry pmPartName field is "Maci". This is only true for SCSI disk drivers. Other, partition-based disk drivers are always checksummed.

The above algorithm is known as the 16-bit driver checksum algorithm. This is because the ROM decrements and tests bytesToSum using a DBRA instruction (which effectively makes bytesToSum a UInt16), so only the first bytesToSum modulo 64 K bytes of the driver are checksummed. This is not a problem if your driver is smaller than 64 K bytes. If your driver is larger, you must be careful for two reasons.

1. The code you use to calculate pmBootCksum must mimic the incorrect behavior and only checksum your driver up to the driver size modulo 64 K.
2. You may want to include your own checksum in the driver to ensure that the driver code is intact.

In some situations where the ROM loads a driver, it does not use the 16-bit checksum algorithm. Specifically, later versions of ATA Manager use a 32-bit driver checksum algorithm, shown below.

static UInt16 ATALoadDoCksum(void *start, UInt32 bytesToSum)
{
    UInt8  *startAsBytes;
    UInt32 result;
    UInt32 i;
    
    startAsBytes = (UInt8 *) start;
    result = 0;
     for (i = 0; i < bytesToSum; i++) {
        result += startAsBytes[i];
        result <<= 1;
        result |= (result & 0x00010000) ? 1 : 0;
    }
    return (UInt16) result;
}

The key difference is that bytesToSum is now expressed as a 32-bit quantity, and the algorithm correctly checksums bytes beyond 64 KB. Further, the 16-bit algorithm never returns a checksum of 0 (it is mapped to $FFFF), while the 32-bit algorithm can return a checksum of 0.

Your formatting utility must set pmBootCksum appropriately, depending on which version of ATA Manager is loading your driver. Furthermore, the ATA driver loader mechanism is updated during the system startup process so that on machines with the old checksum algorithm in ROM, your driver will need a different checksum depending on whether it is loaded at start time or after system startup.

Overall, the best solution to this driver checksum conundrum is:

• make your driver's size less than 64 KB (if necessary, use a boot strap driver to load your main driver), and
• if your driver checksums to 0, add pad bytes until it doesn't.

A Partition of Your Imagination

The original Mac Plus SCSI implementation did not allow the user to specify a startup partition. Obviously this is desired feature, and disk driver developers came up with a number of solutions for this problem. Over the years, Apple has introduced various stages of OS support for booting from a partition.

Developer-Only Solutions

Prior to Apple providing a solution, developers were responsible for engineering their own. Developers quickly noticed that, all things being equal, the Macintosh tends to boot from the first bootable drive in the drive queue. Therefore, disk driver writers arranged to add the startup partition's drive queue element to the drive queue before the non-boot partitions' element. The disk driver's formatting utility provided the user interface for specifying the boot partition.

This technique was relatively effective and stimulated user demand for a reliable mechanism for booting from a partition.

Partition Attribute Support

Eventually, Apple codified this approach and provided support for it in the Startup Disk control panel. The codification came in the form of the kPartitionIsStartup bit in the pmPartStatus field of the partition map, along with a driver Control request, kSetStartupPartition, which allows the Startup Disk control panel to instruct the driver to set that bit.

This standardized the previous non-standard behavior, although it still is not a perfect solution because of variances in the way the ROM startup code chooses a drive from which to start up.

SCSI Manager 4.3

Apple made further refinements to this solution with the introduction of SCSI Manager 4.3. SCSI Manager 4.3 presented new problems to the startup code because it allows for multiple SCSI buses, and it provides full support for SCSI LUNs. So, when SCSI Manager 4.3 was introduced, Apple also introduced a new technique for finding the startup partition, the kdgBoot Driver Gestalt selector.

When the user chooses a drive in the Startup Disk control panel, Startup Disk sends the kdgBoot Driver Gestalt selector to the disk driver controlling that drive. Startup Disk then records the response in PRAM. When the Macintosh boots, it iterates through the drive queue, sending a kdgBoot request to each drive. When it finds a drive with a value matching the value in PRAM, it knows that this is the correct startup drive.

The kdgBoot Driver Gestalt selector is documented in Designing PCI Cards and Drivers for Power Macintosh Computers, page 113. This documentation is accurate for SCSI drivers. For ATA drivers, the DriverGestaltBootResponse response fields should be set as follows.

extDev

The ATA bus number of the device.

partition

The partition number on the bootable partition on the device. As described below, the format of this field is internal to your disk driver.

SIMSlot

ATA devices must set this to kDriverGestaltBootATASIMSlot ($20). [This constant is not currently in Universal Interfaces, Radar ID 2314693.]

SIMsRSRC

If your driver supports ATA 0/1, you must put 0 or 1 in this field to indicate the number of the device on the ATA bus. If your driver does not support ATA 0/1, you must set this to zero. See ATA 0/1 Software Developers Guide for more details on ATA 0/1 support.

ROM-in-RAM (NewWorld)

The ROM-in-RAM architecture, introduced with the iMac, presents new challenges for the startup device selection process. On a ROM-in-RAM machine, Open Firmware is responsible for loading the Mac OS ROM file off the startup partition, and hence Open Firmware must define the startup partition well before Mac OS starts to execute. When the Mac OS ROM starts, it continues booting from the startup partition chosen by Open Firmware to avoid the potential user confusion of loading the Mac OS ROM from one disk and the system software from another.

Open Firmware synthesizes the traditional Macintosh startup process, including:

• Startup drive selection algorithm -- Open Firmware implements the traditional startup drive selection algorithm. It turns out that this algorithm is very complex, although the gist of it is:

  1. if a "snag" key is held down, try booting from the corresponding device,
  2. try booting from the default drive (if any),
  3. then try booting from other drives.

• CODS -- Holding down command-option-delete-shift (CODS) prevents the Open Firmware from booting from the default drive.
• C for CD-ROM -- Holding down the C key forces Open Firmware to boot from the CD-ROM device. This was previously implemented by the "snag" patch but is implemented by Open Firmware in ROM-in-RAM computers.
• Flashing question mark -- If no startup device is available, Open Firmware displays the traditional "flashing question mark" icon (although, in deference to the fact that ROM-in-RAM computers do not have floppy drives, it flashes the question mark inside a folder icon instead of a floppy disk icon).

On ROM-in-RAM computers, the selected default startup device is held in an Open Firmware configuration variable boot-device. This configuration variable holds an Open Firmware path to the default startup device. The Startup Disk control panel generates a path based on the disk driver's response to various Driver Gestalt queries.

It is impossible for Open Firmware to completely mimic the startup drive selection algorithm when it comes to selecting a startup partition. When booting from a partition, boot-device contains the Open Firmware partition number of the startup partition. Unfortunately, there is no reliable way to get this from a disk driver with commonly implemented Driver Gestalt queries.

Prior to Mac OS 9.0, the Startup Disk control panel used tricky heuristics to allow booting from a partition with Apple disk drivers as a temporary measure to solving this problem. The long-term solution; however, is for disk drivers to support a set of new Driver Gestalt queries, which return exactly the information Startup Disk needs to set boot-device. The required Driver Gestalt selectors (kdgDeviceReference, kdgNameRegistryEntry, kdgOpenFirmwareBootSupport, and kdgOpenFirmwareBootingSupport) are described in "DriverGestalt.h" in Universal Interfaces 3.3.

Non-512 Byte Block Devices

The original Mac OS disk driver architecture assumed that all block devices would use 512-byte blocks. Supporting block devices with a different block size is relatively simple, although it gets more complicated if you want to boot from such a device. Non-512 byte block device support is most important for CD-ROM drivers, which use a 2-KB block size.

Just the Basics

The basic rule for supporting non-512 block devices on Mac OS is that the disk driver is responsible for blocking and deblocking all I/O requests to a drive. This discussion assumes that the device block size is an integer multiple of 512, although similar algorithms work for weird device block sizes.

Block Translation

The File Manager makes an I/O request in terms of 512-byte logical block numbers on a particular drive. The disk driver is responsible for translating the logical block number of the request to an actual block number on the drive. If the disk is partitioned, the first step of this translation is to add the offset of the partition to the logical block number; this generates the physical block number. If the device uses 512-byte blocks, the physical block number is the actual block number of the data on the disk. If the device uses non-512 byte blocks, the disk driver must do a further translation, converting the physical block number to a device block number by dividing the physical block number by the number of 512-byte blocks in each physical block.

In addition, the disk driver must block/deblock the request. If the physical block number, or the number of blocks to transfer, is not evenly divisible by the device block size, the disk driver must transfer partial blocks to and from the disk.

The following diagrams shows the entire translation process for two partitions on a 2 KB block device. All numbers on the diagram are in the units labeled in the left column. For example, partition 1 is a 50 MB partition which extends from 0 to 100 mega logical blocks (512-byte blocks), 40 to 140 mega physical blocks (also 512-byte blocks), and 10 to 35 mega device blocks (2 KB byte blocks).

Implementation Notes

A disk driver typically deblocks a request by breaking it into three components. The leading component consists of all the requested physical blocks up to the first device block boundary. The leading component is empty if the requested physical blocks start on a device block boundary.

The main component consists of all the requested physical blocks which are fully encompassed by device blocks. The main component may be empty if the transfer is short. The main component is transferred directly from between the client buffer and the disk.

Finally, the trailing component consists of all the requested physical blocks of the transfer which fall after the last block of the main component. The trailing component is empty if the physical block number plus the number of physical blocks to transfer falls on a device block boundary.

Because you can't transfer a sub-block size request, the leading and trailing components must be transferred through a temporary buffer. You should allocate this temporary buffer when your driver is opened. As the leading and trailing components are always less than one device block (otherwise they would be part of the main component), the temporary buffer need only be as big as a device block. If your device driver is single threaded, you need only allocate a single temporary buffer. If your driver is multi-threaded, you must allocate as many temporary buffers as you allow threads of execution within your driver, or internally serialize the use of the temporary buffer.

The leading and trailing components are read by transferring the device block to the temporary buffer and then copying the appropriate data out of the temporary buffer to the client buffer. The leading and trailing components are written by first reading the current contents of the device to the temporary buffer, then copying the new data from the client buffer to the temporary buffer, then writing the temporary buffer to the device.

The following illustration shows how misaligned read is transferred to the client buffer:

Performance Considerations

The above algorithm is obviously inefficient if transfers are misaligned, that is, if the leading and trailing components are not empty. Misaligned writes are even more expensive than misaligned reads because the disk driver must do an extra I/O to pre-fill the temporary buffer with the existing contents of device block. Worse yet, a misaligned write that has both leading and trailing components takes five I/O operations (read leading, write leading, write main, read leading, write leading).

There are a number of ways to avoid misaligned transfers:

• Your formatting utility should always start partitions (especially file system partitions) on device block boundaries.
• File system clients can issue a Driver Gestalt kdgMediaInfo request to determine the device block size and ensure that transfers are aligned. This is particularly important for write requests.
• As a rule, volume formats should use the above technique to ensure that their allocation blocks are correctly aligned. At a minimum, volume formats should align allocation blocks on 2 KB boundaries to accommodate the most common cases, namely CD-ROM, DVD-ROM/RAM, and magneto-optical devices.

It is strongly recommended that your disk driver cache at least one device block. Many Mac OS programs will transfer data in sequential 512-byte chunks. By caching a single device block, your driver can radically reduce the average time taken to service these requests.

Booting From Non-512 Byte Block Devices

This section is not yet finished and has been omitted in the interests of shipping an initial version of the technote. A future revision of this technote will cover booting from a non-512 byte block device. If you are interested in this topic, please email DTS and ask for a prerelease draft of this section.

Large Volume Support

When Mac OS originally shipped, it supported volume sizes up to 2 GB. This limit was shared by a number of system components, including the File Manager and disk drivers. Large volume support was introduced in two phases.

1. System 7.5 introduced support for volumes larger than 2 GB, up to a size of 4 GB. The semantics of two programming interfaces were changed to accomplish this.
   • PBHGetVInfo does not return the true size of the volumes greater than 2 GB; the volume size and free space are always clipped to 2 GB or less.
   • The dCtlPosition field of the Device Control Entry (DCE) was redefined as an unsigned quantity.
2. System 7.5.2 introduced support for volumes larger than 4 GB, up to a size of a 2 TB. This required two new programming interfaces.
   • PBXGetVolInfo returns the volume size and free space as a 64-bit quantity.
   • The I/O parameter block passed to disk drivers was extended to include a 64-bit field, ioWPosOffset, which supplants dCtlPosition.

The changes to the File Manager programming interfaces are not relevant to this technote; they are documented in DTS Q&A FL 08, "Determining Volume Size." This section describes the changes to the disk driver interface.

Large Volume Interfaces

Supporting volumes between 2 GB and 4 GB was simply a matter of redefining the dCtlPosition field of the DCE and the ioPosOffset field of the IOParam structure to be unsigned longs (UInt32).

To support volumes larger than 4 GB, a new extended I/O parameter block (XIOParam) structure was defined. The original and extended I/O parameter blocks are distinguished by the kUseWidePositioning bit of the ioPosMode field (clear for original, set for extended).

The C definition of the extended I/O parameter block is given below. The key difference is the addition of the ioWPosOffset field, a signed 64-bit quantity which contains the offset of the request.

struct XIOParam {
    QElemPtr            qLink;
    short               qType;
    short               ioTrap;
    Ptr                 ioCmdAddr;
    IOCompletionUPP     ioCompletion;
    OSErr               ioResult;
    StringPtr           ioNamePtr;
    short               ioVRefNum;
    short               ioRefNum;
    SInt8               ioVersNum;
    SInt8               ioPermssn;
    Ptr                 ioMisc;
    Ptr                 ioBuffer;
    long                ioReqCount;
    long                ioActCount;
    short               ioPosMode;
    wide                ioWPosOffset;
};
typedef struct XIOParam XIOParam;
typedef XIOParam *XIOParamPtr;

For software making extended I/O requests, the fields are defined as follows:

qLink
qType
ioTrap
ioCmdAddr

Used internally by the Device Manager.

ioCompletion

For asynchronous requests, you must either set this field to zero or set it to a universal procedure pointer for your completion routine. For synchronous requests, this field is ignored.

ioResult

On completion this field contains the result of the request, which is either noErr (0) or a negative error code. The Device Manager guarantees that this field will be set to ioInProgress (1) until the request is complete.

ioNamePtr

Ignored for _Read and _Write requests.

ioVRefNum

You must set this field to the drive number of the drive you wish to read or write.

ioRefNum

You must set this field to the driver reference number of the device driver controlling the drive you wish to read or write.

ioVersNum
ioPermssn
ioMisc

Ignored for _Read and _Write requests.

ioBuffer

You must set this to point to a data buffer from which data is written, or to which data is read.

ioReqCount

You must set this field to the number of bytes you wish to read or write. For disk driver requests, this must be a multiple of 512 bytes.

ioActCount

On completion this field contains the number of bytes of data that were actually transferred.

ioPosMode

You must set this field to kUseWidePositioning to indicate that this is a wide request. All wide requests use a positioning mode of fsFromStart. You must not specify any other positioning mode (fsAtMark, fsFromLEOF, or fsFromMark). You may also specify rdVerifyMask for read-verify mode, noCacheMask to request that the data not be placed in the cache, or pleaseCacheMask to request that data be placed in the cache.

ioWPosOffset

You must set this field to the offset (in bytes) from the beginning of the disk where the transfer should begin. For disk driver requests, this must be a multiple of 512 bytes.

For disk drivers servicing an extended I/O request, the fields are defined as follows:

qLink
qType

Used internally by the Device Manager.

ioTrap

Your driver must test bit 0 of this field to determine whether the request is a _Read (bit 0 clear) or a _Write (bit 0 set). It must also test noQueueBit (bit 9) to determine whether the request is immediate (bit 9 set) or not. If your driver does not support immediate requests, it must fail the request with a paramErr. Your driver must not test asyncTrpBit (bit 10) to determine whether the request is synchronous or asynchronous. Instead, it should handle all requests as if they were made asynchronously. See Technote 1067 Traditional Device Drivers: Sync or Swim for details.

ioCmdAddr

Used internally by the Device Manager.

ioCompletion

The Device Manager IODone routine will do the right thing with this field. Your driver should ignore this field and handle all requests as if they were made asynchronously. See Technote 1067 Traditional Device Drivers: Sync or Swim for details.

ioResult

Your driver must not read or write this field. Your driver sets this field implicitly when it calls IODone. When your driver has finished a queued request, it should call IODone to signal that the request is complete. IODone performs a number of actions, one of which is to set this field to the error status you passed to the routine in register D0. Your driver must pass a non-positive error status to IODone.

ioNamePtr

Your driver must ignore this field.

ioVRefNum

Your driver must use this field to determine which drive is the target of the request. If your driver does not control a drive with this drive number, it must complete the request with nsDrvErr.

ioRefNum

Your driver may look at this field to determine the driver reference number of the request. This may be useful if the same code is used for multiple device drivers (see Code Sharing).

ioVersNum
ioPermssn
ioMisc

Your driver must ignore these fields.

ioBuffer

Your driver must transfer data to or from the buffer pointed to by this field.

ioReqCount

Your driver must attempt to transfer the number of bytes specified in this field. Your driver may fail a request (with paramErr) if this is not a multiple of 512 bytes.

ioActCount

Before completing the request, your driver must set this field to the number of bytes that were actually transferred.

ioPosMode

Your driver must test the kUseWidePositioning bit to determine whether this is a wide request, as described in the next section. If it is a wide request, your driver must ignore the bottom 2 bits of this field (that is, fsFromStart, fsAtMark, fsFromLEOF, and fsFromMark) and use ioWPosOffset to determine the offset into the drive for the transfer. Your driver may choose to honor the rdVerifyMask, noCacheMask, and pleaseCacheMask in the traditional way.

ioWPosOffset

Your driver must transfer data from this offset (in bytes) into the drive. Your driver may fail a request (with paramErr) if this is not a multiple of 512 bytes. If ioWPosOffset is negative or ioWPosOffset plus ioReqCount is beyond the end of the drive, your driver must fail the request with a paramErr.

Supporting Large Volumes in Your Driver

To support large volumes correctly, your driver must implement the following:

• Your driver must return true in response to the kdgWide Driver Gestalt selector. You may want to use the GetDriverGestaltBooleanResponse macro to ensure that you set the correct response byte in the parameter block.
• When handling all _Read or _Write requests, your driver must check whether the kUseWidePositioning flag is set in ioPosMode. If it is, you must cast the parameter block to an XIOParam and do the I/O at the 64-bit offset specified in ioWPosOffset. This type of request is known as a wide request.
• If kUseWidePositioning is not set, your driver must do the I/O at the offset specified by dCtlPosition. You must cast this signed value to an unsigned quantity (UInt32) to correctly handle offsets from 2 GB to 4 GB. This type of request is known as a narrow request.

There are some important caveats of which you should be aware.

• There is no guarantee that the system will check with Driver Gestalt before issuing a wide request. The system expects that any driver controlling a drive larger than 4 GB will respond to wide request correctly. Similarly, the system expects that a driver controlling a drive whose size is between 2 GB and 4 GB is smart enough to treat dCtlPosition as unsigned.
• There is no guarantee that the system will always use wide requests when talking to a drive larger than 4 GB. In fact, the system currently decides on a request-by-request basis whether to use a wide or a narrow request, based on the request's offset on the drive. However, you must not rely on this behavior; you must handle wide requests to offsets less than 4 GB correctly.
• The dCtlPosition field of the DCE is a 32-bit quantity, thus it cannot accurately reflect the position of the current I/O beyond the 4 GB boundary. You should ignore dCtlPosition for wide requests and use it only for narrow requests.

Notes for Developers Calling Disk Drivers

If you're writing software that issues _Read or _Write requests to a disk driver, you must be careful to avoid some common pitfalls. Specifically, you should follow the recommendations given below.

• You should always use an ioPosMode of fsFromStart when calling a disk driver. Because dCtlPosition cannot accurately reflect the position beyond 4 GB, other positioning modes do not work as expected in all cases.
• Before issuing a wide request, you should call Driver Gestalt to determine whether the driver supports wide requests.
• If the driver supports wide requests, you may choose to always use wide requests for that driver. However, for maximum compatibility, DTS recommends that you take the same approach as the system by deciding to use a wide or narrow request based on the offset into the drive.

The following code snippet implements these recommendations.

static void SetWidePosOffset(UInt32 blockOffset, XIOParamPtr pb)
    // Set up ioPosMode and either ioPosOffset or ioWPosOffset for a
    // device _Read or _Write.
{
    pb->ioWPosOffset.lo = blockOffset << 9;  // convert block number
    pb->ioWPosOffset.hi = blockOffset >> 23; // to wide byte offset
 
    if ( pb->ioWPosOffset.hi != 0 ) {
        // Offset on drive is >= 4G, so use wide positioning mode
        pb->ioPosMode = fsFromStart | (1 << kWidePosOffsetBit);
    } else {
        // Offset on drive is < 4G, so use regular positioning mode,
        // and move the offset into ioPosOffset
        pb->ioPosMode = fsFromStart;
        ((IOParam *)pb)->ioPosOffset = pb->ioWPosOffset.lo;
    }
}

In addition, you should never call PBReadImmed or PBWriteImmed on a disk driver unless you know, in advance, that the disk driver supports such requests. Many disk drivers fail to handle Immediate requests properly. Because immediate requests result in the disk driver possibly being reentered, these problems are hard to detect and debug.

How the ROM Loads SCSI and ATA Drivers

This section describes how the ROM loads SCSI and ATA drivers from a driver partition. Understanding this process is critical to an understanding of the chaining driver architecture, and useful for general disk driver writers.

When a Macintosh boots, code in the ROM scans each SCSI and ATA bus for block devices in a bus-specific manner. Once it has found a potentially bootable block device, the ROM attempts to load a driver from that device. The ROM executes the following procedure to load a driver.

1. It first reads device block 0 of the disk. This is the driver descriptor map (DDM) and is structured as the Block0 data type defined in "SCSI.h". It checks that block 0 is a valid DDM by comparing the sbSig field to sbSIGWord ($4552 or 'ER'). If the DDM is not valid, the ROM ignores the device.
2. It then reads device block 1 of the disk and looking for the first entry of the partition map. A partition map entry is represented by the Partition data structure in "SCSI.h". For the partition to be recognized, the pmSig field must be newPMSigWord ($5453 or 'PM'). The ROM uses the pmMapBlkCnt field of this first partition to determine the size of the partition map as a whole.
3. The ROM then searches the DDM for the first driver that is compatible with this bootable bus. The DDM contains an array of DDMap structures. The key field in this structure is ddType, which identifies the type of driver defined by the structure. If the device is attached to a SCSI bus, the ROM looks for a DDMap whose ddType is kDriverTypeMacSCSI. If the device is attached to an ATA bus, the ROM looks for a DDMap whose ddType is kDriverTypeMacATA.
4. The ROM then searches (by reading consecutive device blocks) the partition map for the chosen driver's partition map entry (whose pmParType starts with "Apple_Driver" and whose pmPyPartStart equals the ddBlock field of the DDMap of the chosen driver). It stores this partition map entry in a temporary memory block.
5. The ROM then searches (by reading consecutive device blocks) the partition map for the first HFS partition (whose pmParType is "Apple_HFS"). It stores this partition map entry in a temporary memory block.
6. The ROM then uses the driver's DDMap to read the driver into memory. It first allocates a pointer block in the system heap to hold the driver (the size of this block is the size of the driver in blocks (ddSize) multiplied by the disk's block size (sbBlkSize)) and then reads the driver off the disk (starting from ddBlock) into that buffer.
7. Next, the ROM checksums the driver to ensure its validity. For more information on the exact details of the checksum, see Driver Checksums.
8. The ROM then calls the driver's entry point. The exact calling conventions are described below. The driver is expected to install itself in the unit table, open itself, and create drive queue elements for each mountable partition on the disk. (The exact definition of "mountable" is covered in Cooperating with File System Manager.)

If any of these steps fail, the ROM assumes that the device is not bootable and attempts to boot from the next available device.

Each driver has two possible entry points. The primary entry point is at the beginning of the memory block holding the driver. The secondary entry point is 8 bytes into the memory block holding the driver. In general, the primary entry point is called when an "old" driver is loaded, or a "new" driver is loaded by an 'old' ROM, and the secondary entry point is used when a 'new' ROM load a "new" driver. The secondary entry point has extra parameters that make sense in the 'new' ROM environment.

The exact definition of "old" and "new" depends on the bootable bus. For SCSI, a "new" ROM is one that contains SCSI Manager 4.3, and a "new" driver is indicated by the bytes "43" in the two bytes following the "Apple_Driver" in pmParType. For ATA, an 'old' ROM is one that contains ATA Manager 1.0. All newer versions of ATA Manager use the secondary entry point. A 'new' ATA Manager will always call the secondary entry point of the driver.

Both entry points use register-based calling conventions. The register usage is shown in the table below:

Register D3

Old Apple SCSI drivers require that register D3 be set to a non-zero value in order to boot correctly. This bug was fixed in September 1996 although, if you are writing a SCSI disk -mounting utility, you may still encounter these old drivers.

Register D5

The data in register D5 depends on both the bootable bus and the entry point called. The following table indicates the possible combinations.

The format of DeviceIdentATA is given below.

struct DeviceIdentATA {
    UInt8 diReserved;
    UInt8 busNum;
    UInt8 devNum;
    UInt8 diReserved2;
};
typedef struct DeviceIdentATA   DeviceIdentATA;
typedef DeviceIdentATA *        DeviceIdentATAPtr;

The fields have the following meaning:

diReserved

Reserved. When calling a disk driver, the ROM sets this to 0; however, in the case described below, this field contains meaningful data.

busNum

The ATA bus number.

devNum

If the machine has ATA 0/1 support, this is the device number of the device on that bus. Otherwise, it must be zero.

diReserved2

Reserved. Set to 0.

In some cases (such as the entry point to a patch loaded by the Apple patch driver), the diReserved field is used to distinguish between a DeviceIdent and DeviceIdentATA. The appropriate values for this field are given below.

enum {
    kBusTypeSCSI        = 0,
    kBusTypeATA         = 1,
    kBusTypePCMCIA      = 2,
    kBusTypeMediaBay    = 3
};

enum {
    kSecondaryEntryPointCalled  = 29,    // 1 => secondary entry point called
    kDontMountVolumes           = 30,    // 1 => don't mount any partitions
    kAfterSystemStartupTime     = 31     // 1 => post-system startup load
};

Register D0

The significance of register D0 on return from your driver's entry point varies depending on the manager that loaded your driver.

• For ATA Manager, your driver should return an error result in the low word of register D0 and, if the driver successfully installed, its driver reference number in the high word (or a high word of zero otherwise). If you return an error value other than noErr, ATA Manager will unload your driver code from memory.
• For SCSI Manager 4.3, the contents of register D0 are always ignored. SCSI Manager 4.3 will never unload your driver from memory. With some clever coding, you can unload the bulk of your driver code upon a failed installation, if you feel that level of polish is necessary.
• For old SCSI Manager, the situation varies depending on the particular ROM.
  • The Mac Plus will treat register D0 as an error result and unload your driver if you return a non-zero value.
  • Subsequent computers ignore the contents of register D0. If your driver fails to install and you want its code to be unloaded, you can return to the return address plus 4 bytes, which signals this to SCSI Manager. Doing this on a computer running SCSI Manager 4.3 will crash the system.

Loading FireWire Drivers

This section is only available under non-disclosure agreement. Please contact DTS for details.

There are circumstances under which software wants to remove the driver for a disk at runtime. For example, a formatting utility might want to reformat a disk which was previously controlled by another driver. If the driver controlling the disk is written by you, it is easy to coordinate this takeover. On the other hand, if the driver controlling the disk is unknown to you, taking over the disk is tricky to do safely. This process is known as a hostile takeover.

Note:
Do not use the term "hostile takeover" in your user interface. It is likely to scare and confuse users.

To initiate a hostile takeover of a device, you must take the following steps.

1. Warn the user that you are attempting something that risks both crashing and data loss.
2. Verify that there are no volumes mounted on drives controlled by the device. Do this by iterating through the mounted volumes (by making indexed calls to PBHGetVInfo) checking that ioVDRefNum is not equal to the driver reference number of the driver in question. If there are volumes mounted using the driver, you may want to unmount the volumes yourself using PBUnmountVol.
3. If the driver supports Driver Gestalt, issue a kdgPurge Driver Gestalt request. If this succeeds, you can check the purgePermission to see whether the driver supports the Close request. If it doesn't, a hostile takeover is not possible without restarting.
4. Call CloseDriver to close the driver, which returns one of the following results.
   1. noErr -- The driver closed successfully. Continue with the next step.
   2. closErr (or any other error) -- The driver could not be closed. A hostile takeover is not possible without restarting.

Note:
Never close a driver with FSClose or PBClose. If you're closing a driver, always use CloseDriver. Similarly, if you're opening a driver, always use OpenDriver. These routines provide the correct glue to the _Open and _Close traps to ensure that you are acting on a driver, not a file, or a desk accessory, or a slot driver.

1. Just to be certain, you should check whether any drive queue elements belonging to the driver remain in the drive queue. If there are, the driver's implementation of the Close request is broken and a hostile takeover is not possible without restarting.
2. If you issued a kdgPurge request (step 3 above) and kbRemoveOk was set in the purgePermission response, you can call DriverRemove to remove the driver from the unit table. If the driver doesn't support Driver Gestalt, or kbRemoveOk is not set, the hostile takeover is complete. The driver is still installed in the unit table but it should be a relatively benign memory leak.
3. If you issued a kdgPurge request (step 3 above) and kbPurgeOk was set in the purgePermission response, you can call DisposePtr on purgeDriverPointer to remove the driver's code from memory. If the driver doesn't support Driver Gestalt, or kbPurgeOk is not set, the hostile takeover is complete. The driver code is still in memory but it should be a relatively benign memory leak.

Note:
You might think that you can just dispose dCtlDriver, but that is not correct. dCtlDriver may not be a valid Memory Manager pointer. Specifically, for SCSI and ATA drivers, dCtlDriver typically points some number of bytes into the pointer block.

If a hostile takeover is not possible without restarting -- or the user declines your offer to attempt one -- you are forced to restart the computer to take over the disk. You can overwrite the DDM to eliminate all foreign drivers from the disk and then restart the computer. Because there are no drivers in the DDM, the disk will not be mounted and you will be free to use it as you wish.

IMPORTANT:
Do not expect any data on the disk to survive this operation. While most drivers use the standard partition format, there are some non-standard partition formats (such as RAID striping) for which the driver is the only thing that "holds it all together". In those cases, eliminating the driver typically eliminates the data. The only way around this is to treat each of the common RAID formats as a special case in your hostile takeover software.

Note:
Some third-party formatting utilities implement a more powerful but less safe approach to hostile takeovers. Specifically, if the check for orphaned drive queue elements (step 5 above) fails, the utility simply dequeues the orphaned drive queue elements and unregisters the drives with the appropriate manager. This technique works in most cases, although it leaks memory (the orphaned drive queue elements) and may potentially cause a system crash. If you implement this technique, be sure to warn the user of the possible consequences.

File Exchange (né PC Exchange)

Foreign file systems (such as File Exchange) require your disk driver to do extra work to support the mounting of non-HFS volumes. While this extra work is not hard, it has been poorly documented. This section explains the correct way to support foreign file systems in your disk driver.

Note:
For an in-depth explanation of the whole volume mounting process, see Partition Handling: Background and Rationale later in this section.

Cooperating with File System Manager

There are two steps you must take to fully support File System Manager in your disk driver. The first step is to support the File Exchange interface, which is described in the next section. The second step is related to the way your disk driver scans a bus and creates drive queue elements for devices on that bus. Your current algorithm might look something like that shown below.

on scanForDevices
  scan bus for devices
  for each device found on the bus
    if the disk contains an Apple partition map
      for each partition on the disk
        if kPartitionIsMountedAtStartup is set in pmPartStatus
          if the partition is of type "Apple_HFS"
            create a drive queue element with FSID of 0
            post a "disk inserted" event
          end-if
        end-if
      end-for
    end-if
  end-for
end scanForDevices

on scanForDevices
  clear InformFSM flag
  scan bus for devices
  for each device found on the bus
    if the disk contains an Apple partition map
      for each partition on the disk
        if kPartitionIsMountedAtStartup is set in pmPartStatus
          if the partition is of type "Apple_HFS"
            create a drive queue element with FSID of 0
            post a "disk inserted" event
          else if the partition is of a known non-disk type
            do nothing
          else
            create a drive queue element with FSID of fsmGenericFSID
            set InformFSM flag
          end-if
        end-if
      end-for
    else
      create a drive queue element with FSID of fsmGenericFSID \
             that encompasses the entire drive
      set InformFSM flag
    end-if
  end-for
  if InformFSM flag
    call InformFSM(fsmDrvQElChangedMessage)
  end-if
end scanForDevices

IMPORTANT:
InformFSM is a generic utility routine by which your disk driver can send messages to FSM. It is documented in Guide to the File System Manager.

The basic algorithm, as shown above, is surprisingly easy. However, complications arise if your disk driver might load before FSM. This can happen in the following circumstances:

1. If your disk driver is loaded out of a driver partition in a partition map.
2. If your disk driver loads from a system extension on an old system. Systems prior to System 7.5 did not have FSM in the System file, so FSM loaded at INIT time. The system extension which loads your driver might run before the one loading FSM.

Note:
There are two common cases where FSM might load from a system extension:

1. Early versions of PC Exchange contain an equally early version of FSM embedded in the extension. When PC Exchange loads, it checks to see whether FSM is already present in the system. If it isn't, it loads the embedded version of FSM.
2. FSM plug-in developers can license a system extension, "File System Manager", to install with their FSM plug-in on older systems.

If your disk driver loads before FSM, the above algorithm has a number of problems. Firstly, InformFSM is not implemented until FSM loads, so calling it would be bad. Secondly, the support for fsmGenericFSID is implemented by FSM, so creating a drive queue element with that FSID is a bad idea unless FSM is installed.

The solution to this is to defer both activities until FSM loads. If system startup completes without FSM loading, you simply do not perform these steps. You can poll for both of these events in your driver's accRun handler. The new algorithm is shown below.

on scanForDevices
  determine whether FSM is installed
  clear InformFSM flag
  scan bus for devices
  for each device found on the bus
    if the disk contains an Apple partition map
      for each partition on the disk
        if kPartitionIsMountedAtStartup is set in pmPartStatus
          if the partition is of type "Apple_HFS"
            create a drive queue element with FSID of 0
            post a "disk inserted" event
          else if the partition is of a known non-disk type
            do nothing
          else
            if FSM available
              create a drive queue element with FSID of fsmGenericFSID
            end-if
            set InformFSM flag
          end-if
        end-if
      end-for
    else
      if FSM available
        create a drive queue element with FSID of fsmGenericFSID \
               that encompasses the entire drive
      end-if
      set InformFSM flag
    end-if
  end-for
  if InformFSM flag
    if FSM available
      call InformFSM(fsmDrvQElChangedMessage)
    else
      set gPollForFSM
      set dNeedTime in dCtlFlags
    end-if
  end-if
end scanForDevices
 on accRun
  if gPollForFSM
    if FSM available then
      call scanForDevices again
      clear gPollForFSM
      clear dNeedTime in dCtlFlags (unless you need it for other reasons)
    else if startup time is over
      clear gPollForFSM
      clear dNeedTime in dCtlFlags (unless you need it for other reasons)
    end-if
  end-if
end accRun

Note:
You can determine whether system startup is complete using the technique described in Disk Drivers and the System Heap.

For more information about why this algorithm is necessary, see Partition Handling: Background and Rationale.

Finally, if you mount a large number of disks simultaneously, you may run afoul of the system event queue's size limit. On current systems (Mac OS 9.0), the system event queue is limited to 48 events. If the system event queue is full and you post a "disk inserted" event, the event is ignored. There are two aspects to this problem:

1. If you explicitly posted the "disk inserted" event by calling PostEvent, you will find that an event posted while the event queue is full will cause the first event in the queue to be dropped. PostEvent will not return an error to indicate that an event was dropped.
2. You also receive no notification that the event queue is full if you implicitly post "disk inserted" events by calling InformFSM with the fsmDrvQElChangedMessage selector.

There is a simple algorithm that handles both of these cases:

1. When a drive is ready for operation (its disk has just been inserted, or you detected it during your initial scan for devices), set a flag in your per-drive storage to indicate that a "disk inserted" event is pending.
2. Inform the system that the disk was inserted as described above (either by posting a "disk inserted" event or by calling InformFSM with the fsmDrvQElChangedMessage selector).
3. When any I/O is done to the drive, clear the disk inserted pending flag. I/O to the drive indicates that some file system has queried the drive to determine whether to mount a volume on it, which implies that the "disk inserted" event was successfully processed.
4. At accRun time, check for any drives with the disk inserted pending flag still set. If you find one it is likely that the "disk inserted" event was lost, so you should reinform the system of the disk insertion.

Implementing File Exchange Support

This section describes how you should implement the File Exchange interface in your disk driver.

Note:
The requests described here have been documented in a number of places, including Designing PCI Cards and Drivers for Power Macintosh Computers, page 114, and "PCX and Large Volume Drivers." However, none of the previous descriptions are sufficiently detailed for you to implement the requests correctly.

A disk driver that supports the following Control and Status requests must implement the kdgAPI selector to indicate that it does. For more information about Driver Gestalt, see the Driver Gestalt section of this technote.

Partition Information Record

The partition information record (partInfoRec) is a structure used to store information about a partition on a disk. The fields of the structure are:

SCSIID

If the underlying device is connected via a SCSI interface, this field holds the SCSI Manager DeviceIdent of the device. If the device is connected via an ATA interface, this field holds the ATA Manager ataDeviceID (a structure defined in ATA 0/1 Software Developers Guide). Devices connected via other interfaces can use whatever value makes sense to uniquely identify the device on that bus (typically this is the same 32-bit number returned by the kdgDeviceReference Driver Gestalt selector). If no value makes sense, a driver must clear this field.

physPartitionLoc

The block number of the first block in the partition.

partitionNumber

The physical block number of the partition map entry of this partition.

Note:
You can determine the interface used by the device issuing the kdgInterface Driver Gestalt query. Drivers that support File Exchange should also support this Driver Gestalt selector.

Note:
For more information about the ataDeviceID structure, consult the ATA Device 0/1 Software Developer Guide. This structure is not the same as the DeviceIdentATA structure, defined above.

In response to this request, your disk driver must create a new drive queue element. The fields of the new drive queue element must be filled out as described below.

drive flags (the 4 bytes prior to qLink)

Inherited from the supplied drive queue element.

qLink

Set up when you add the drive to the drive queue using AddDrive.

qType

Inherited from the supplied drive queue element.

dQDrive

Must be set to a new unique drive number.

dQRefNum

Must be set to your driver's reference number.

dQFSID

Inherited from the supplied drive queue element.

dQDrvSz

Inherited from the supplied drive queue element.

dQDrvSz2

Inherited from the supplied drive queue element.

partition offset (typically held in extra bytes beyond dQDrvSz2)

Inherited from the supplied drive queue element.

Your driver must return the new drive queue element in the memory pointed by csParam[0..1]. You must not post a "disk inserted" event for the new drive, or send the fsmDrvQElChangedMessage message to FSM.

IMPORTANT:
This request is typically issued as a synchronous request, which can cause problems if your driver needs to allocate memory to create the new drive queue element. To avoid this problem, DTS recommends that all clients issue this as an immediate request. However, to work with old clients, your driver should be prepared to handle all possible request modes.

IMPORTANT:
Your driver should be prepared for the incoming value of the drive queue element pointed to by csParam[0..1] being nil, or some other value which is not a pointer to one of your driver's drive queue elements. In that case, your driver should initialize the fields of the new drive queue element to default values.

Trap

_Control

Mode

Synch, Async

csCode

SInt16

->

kRegisterPartition (50)

csParam[0..1]

DrvQElPtr

->

The drive queue element whose partition is to be changed

csParam[2..3]

UInt32

->

The block number of the first block in the partition

csParam[4..5]

UInt32

->

The size (in blocks) of the partition

In response to this request, your disk driver must retarget the specified drive queue element to represent the given partition on the disk. After this request, the drive queue element must represent a partition that starts at the block specified by csParam[2..3] and is of the size specified by csParam[4..5].

You must not post a "disk inserted" event for the drive, or send the fsmDrvQElChangedMessage message to FSM.

IMPORTANT:
The effects of this request are limited to the drive queue element in memory. This request must not change the partitioning scheme on the disk.

Trap

_Control

Mode

Synch, Async

csCode

SInt16

->

kProhibitMounting (52)

csParam[0..1]

partInfoRec *

->

A pointer to a partInfoRec that describes the partition which is not to be mounted at startup

In response to this request, your disk driver must mark the partition specified csParam[0..1] such that it isn't mounted at system startup.

IMPORTANT:
The effects of this request are permanently applied to the partition map on the disk.

Note:
Modern versions of File Exchange do not require your driver to support this request (partly because it is functionally equivalent to kClearPartitionMount). If you decide not to support it, make sure to return controlErr.

Note:
The partition is completely determined by the fields of the partition information record, not by the ioVRefNum field of the parameter block.

Trap

_Status

Mode

Synch, Async

csCode

SInt16

->

kGetPartInfo (51)

ioVRefNum

SInt16

->

The drive number of the drive whose partition information is requested

csParam[0..1]

partInfoRec *

->

A pointer to a partInfoRec where the partition information is placed

In response to this request, your disk driver must place partition information about the specified drive in the partition information record pointed to by csParam[0..1].

Note:
Your driver's response to this request has a non-obvious effect on the Disk Initialization Package, especially the DIReformat call. The Disk Initialization Package prevents the user changing the file system on a drive that exists on a partitioned disk. It does this to prevent the data on the partition getting out of sync with the partition type (pmParType) in the partition map entry. For example, if the user could reformat an existing HFS partition to be in DOS FAT format, the partition data would be in DOS FAT format while the pmParType would still be "Apple_HFS". This is obviously not a good thing (the ROM might attempt to boot from a DOS FAT partition!), so the Disk Initialization Package prevents it.

This raises the question, how does the Disk Initialization Package know whether a drive is a partition on a disk. The algorithm used is shown below.

on driveIsAPartition drive
  if drive's driver supports File Exchange requests (kdgAPI)
          and kGetPartInfo on drive succeeds then
    return physPartitionLoc != 0
  else
    return drive's driver's unit number in [32..39]
  end-if
end driveIsAPartition

The gist of this algorithm is that, if your driver supports File Exchange requests, the drive's partition must start at the beginning of the disk for the Disk Initialization Package to allow a change of format. Alternatively, if your driver does not support File Exchange requests, it is considered to have partitions if its unit number falls in the range reserved for classic SCSI Manager drivers.

If other demands on your driver prevent it from being reformatted by the above algorithm, you will probably need to include reformat support in your formatting utility.

DTS has requested a better solution to this problem [Radar ID 2287925].

Trap

_Status

Mode

Synch, Async

csCode

SInt16

->

kGetPartitionStatus (50)

csParam[0..1]

partInfoRec *

->

A pointer to a partInfoRec that describes the partition to be queried

csParam[2..3]

SInt16 *

->

A pointer to an SInt16. On return, this holds the vRefNum of the volume represented by this partition, or 0 if no volume is represented by this partition.

In response to this request, your disk driver must determine whether the partition described by the partition information record pointed to by csParam[0..1] is mounted and return the volume reference number of the volume in the SInt16 pointed by csParam[2..3], or 0 if the partition is not mounted.

Note:
The partition is completely determined by the fields of the partition information record, not by the ioVRefNum field of the parameter block.

Using These Requests

This section explains how you might utilize the File Exchange driver requests in your application (or FSM plug-in) to access portions of a partitioned disk that lie outside of the HFS partitions.

WARNING:
Many of the File Exchange driver requests require you to pass a pointer to a buffer. As explained in Private Requests and Virtual Memory, you must hold these buffers (in the VM sense) to prevent fatal page faults.

Note:
This section contains a number of routines which demonstrate the use of the File Exchange interface. Some of the details have been removed for brevity. Moreover, the routines rely on other utility routines that are not included here. The full source code for these routines is available in the MoreDisks module of the DTS MoreIsBetter sample code library.

The first step of using the File Exchange interface is to create a drive queue element that targets the section of the disk you wish to read or write. The following code snippet shows how this might be done.

extern pascal OSErr MoreCreateNewDriveQueueElement(SInt16 driveToClone,
UInt32 firstBlock, UInt32 sizeInBlocks, SInt16 *newDrive)
    // See comment in interface part.
{
    OSErr err;
    CntrlParam pb;
    DrvQElPtr drvQEl;
     // First check that the driver supports the File Exchange
    // interface.
        
    err = noErr;
    if ( ! MoreDriveSupportFileExchange(driveToClone) ) {
        err = controlErr;
    }
    
    // Find the drive queue element associated with
    // driveToClone.  This is an input parameter to
    // kGetADrive.
    
    if (err == noErr) {    
        err = MoreUTFindDriveQ(driveToClone, &drvQEl);
    }
    
    // Make the kGetADrive request to the driver.  Because
    // we pass a pointer to memory outside of the parameter
    // block (drvQEl) and the driver might be a paging device,
    // we must hold drvQEl (and make sure to unhold it later!).
    
    if (err == noErr) {
        err = SafeHoldMemory(&drvQEl, sizeof(drvQEl));
        if (err == noErr) {
            pb.ioVRefNum = driveToClone;
            pb.ioCRefNum = MoreGetDriveRefNum(driveToClone);
            pb.csCode = kGetADrive;
            *((DrvQElPtr **) &pb.csParam[0]) = &drvQEl;
             err = PBControlSync((ParmBlkPtr) &pb);
            if (err == noErr) {
                *newDrive = drvQEl->dQDrive;
            }
            (void) SafeUnholdMemory(&drvQEl, sizeof(drvQEl));
        }
    }
    
    // Now retarget the new drive to the partition on the
    // disk specified by firstBlock and sizeInBlocks.  We do
    // this in the create call because some disk drivers
    // don't always inherit the partition information from
    // the drive that was cloned.
    
    if (err == noErr) {
        err = MoreSetDrivePartition(*newDrive, firstBlock, sizeInBlocks);
    }
    
    return err;
}

This routine works in two parts. First, it finds the drive queue element associated with driveToClone and clones it using a kGetADrive request to the driver. Then, it sets the new drive's partition location and size using MoreSetDrivePartition, which is shown below.

     extern pascal OSErr MoreSetDrivePartition(SInt16 drive, UInt32 firstBlock, 
     UInt32 sizeInBlocks)
    // See comment in interface part.
{
    OSErr err;
    CntrlParam pb;
    DrvQElPtr drvQEl;
    
    // First check that the driver supports the File Exchange
    // interface.
        
    err = noErr;
    if ( ! MoreDriveSupportFileExchange(drive) ) {
        err = controlErr;
    }
    
    // Find the drive queue element associated with
    // drive.  This is an input parameter to
    // kRegisterPartition.
    
    if (err == noErr) {    
        err = MoreUTFindDriveQ(drive, &drvQEl);
    }
    
    // Make the kRegisterPartition Control request.  We
    // don't need to hold any memory because all the
    // parameters to this Control request are entirely
    // contained within the parameter block.
     if (err == noErr) {
        pb.ioVRefNum = drive;
        pb.ioCRefNum = MoreGetDriveRefNum(drive);
        pb.csCode = kRegisterPartition;
        *((DrvQElPtr *) &pb.csParam[0]) = drvQEl;
        *((UInt32 *) &pb.csParam[2]) = firstBlock;
        *((UInt32 *) &pb.csParam[4]) = sizeInBlocks;
         err = PBControlSync((ParmBlkPtr) &pb);
    }
    
    return err;
}

Once you have a drive queue element that spans the blocks you're interested in, you can read and write those blocks using standard Device Manager routines, for example, PBReadSync. The next listing shows how this might be done.

static OSErr ReadBlock(SInt16 drive, UInt32 blockNumber, void *blockBuffer)
{
    OSErr err;
    IOParam pb;
    
    pb.ioVRefNum = drive;
    pb.ioRefNum = MoreGetDriveRefNum(drive);
    pb.ioBuffer = blockBuffer;
    pb.ioReqCount = 512;
    pb.ioPosMode = fsFromStart;
    pb.ioPosOffset = blockNumber * 512;
    err = PBReadSync( (ParmBlkPtr) &pb );
    return err;
}

Partition Handling: Background and Rationale

To understand the current disk driver architecture, you really need to understand the history of how it evolved, starting with the floppy disk drives on the Mac 128.

Mac 128 Disk Driver

When the original Mac shipped all disks were floppy disks, which did not support partitions. The floppy disk driver would create a single drive queue element that represented the entire disk, and the File Manager used this drive as the entire volume. There was a one-to-one translation between logical blocks on the volume (blocks that the File Manager requests) and physical blocks on the disk.

For example, on a floppy disk, if the File Manager requests block 64, the disk driver would simply return block 64.

Disk insertion was handled with the following algorithm:

1. The disk driver created a drive queue element for each physically attached floppy drive.
2. When the user inserted a disk in a drive, the driver posted a disk inserted (diskEvt) event for that drive.
3. The next time the application called GetNextEvent (a predecessor to WaitNextEvent), the (Toolbox) Event Manager got the "disk inserted" event and called _MountVol.
4. _MountVol only recognized built-in file systems, such as MFS and HFS. An attempt to mount an unsupported file system would cause _MountVol to return an error.
5. The (Toolbox) Event Manager put the error result from _MountVol into the high word of the message field of the EventRecord, and returned the "disk inserted" event to the application.
6. The application saw the "disk inserted" event and examined the high word of the event's message field. If the value was not zero, the "disk inserted" event was "bad" and the application called the Disk Initialization Package's DIBadMount routine. DIBadMount would give the user the opportunity to initialize or eject the disk.

SCSI and Partitions

The introduction of SCSI hard disk devices on the Mac Plus made this situation more complex. Hard disk devices support multiple partitions. The File Manager was not changed to recognize these partitions, so the burden of supporting partitions fell on the disk driver. When a disk is partitioned, the disk driver must read the partition map and creates a drive queue element for each HFS partition (a partition whose pmParType is "Apple_HFS") on the disk.

Thus, each drive queue element on a partitioned disk contains an implicit translation from logical blocks to physical blocks. For example, if you have a partition that starts at block 1024 and continues for 4096 blocks, the driver creates a drive queue element for a drive whose size is 4096 blocks. When the system reads logical block 64 on that volume, the driver knows that it must translate that to physical block 1088 (that is, 1024 + 64) on the disk.

The new disk insertion algorithm was:

1. The ROM or a system extension loaded the disk driver.
2. The disk driver parsed the partition map looking for all the partitions of type "Apple_HFS". For each found partition, the driver would create a drive queue element and post a "disk inserted" event.
3. If the driver was being loaded at system startup, the Start Manager would call _MountVol to mount the startup volume. It would then boot from that volume. Later, when the Finder launched and started calling GetNextEvent, the "disk inserted" events for other partitions would be processed.
4. If the driver was being loaded after system startup, the process would proceed as from step 3 above.

This works just fine for disks with the Apple partition map and HFS partitions, where the driver recognizes both the partition map format and the "Apple_HFS" partition map entries, and creates the appropriate drive queue elements. However, it doesn't allow foreign disk formats to be handled correctly, in two important cases.

1. The partition map contains non-HFS partitions (such as "Apple_PRODOS" or "Apple_UNIX_SVR2" (A/UX) partitions) -- When confronted by a non-HFS partition, the driver has a difficult choice. If it creates a drive queue element for the partition and a suitable foreign file system is not installed, the system asks the user whether they want to initialize the partition. Probably not good. On the other hand, if it doesn't create a drive queue element for the partition, there is no way for a foreign file system to access the data on the partition. To safeguard user data, most drivers choose the second alternative.
2. The partition map format is unrecognized -- As Mac OS loads disk drivers from a partition on the disk, it is rare that a disk driver is loaded for a non-Apple partitioned disk. However, if a driver is loaded (by a system extension, for example) for a disk with an unrecognized partition map (such as a DOS partition map), it faces the same difficult choice described above. Most drivers resolve this issue by simply not creating any drive queue elements for disks with an unrecognized partition map.

A foreign file system (such as a File System Manager plug-in) is responsible for controlling a volume mounted on a particular drive (represented by a drive queue element). If there is no drive queue element for a partition, there is no obvious way to create one. Similarly, if there is no driver for a particular disk (because the disk doesn't have an Apple partition map to load it from), there is no easy way for the foreign file system to read from or write to the disk.

File System Manager

When File System Manager was introduced, it defined a new way for disk drivers to announce the arrival of new drive queue elements. This mechanism allows disk drivers to create drive queue elements for non-Apple partitions, free from the fear of the dreaded "This is not a Macintosh disk. Would you like to initialize it?" dialog.

The new algorithm works as described below:

1. When the disk driver loads, it parses the partition map. For each partition of type "Apple_HFS", the driver creates a drive queue element and posts a "disk inserted" event. For other partition types, the disk driver creates a drive queue element whose FSID is fsmGenericFSID and calls InformFSM with the fsmDrvQElChangedMessage message. If it can't recognize the partition map, the driver just creates a single drive queue element whose FSID is fsmGenericFSID and calls InformFSM with the fsmDrvQElChangedMessage message.
2. When InformFSM is called with the fsmDrvQElChangedMessage message, FSM posts a "disk inserted" event for the drive if all the following conditions are met:
   • the drive's FSID is not zero,
   • the drive's FSID is not fsmIgnoreFSID,
   • the drive does not already have a volume mounted on it, and
   • the drive's FSID is fsmGenericFSID or the drive's FSID matches the FSID of one of the installed FSM plug-ins.
3. Each "disk inserted" event is handled as before, except:
   1. FSM passes _MountVol requests to external file systems, which have the opportunity to claim the drive as a foreign volume.
   2. FSM tail patches _MountVol. If _MountVol fails and the drive on which the mount was attempted has the FSID of fsmGenericFSID, FSM causes _MountVol to return nsDrvErr. This error code, when passed back to the application and hence on to DIBadMount, causes DIBadMount to not display the disk initialization dialog.

The effect of these changes is that disk drivers are now free to create a drive queue element for any partition and will not trigger the Disk Initialization Package as long as they set the FSID of the drive to fsmGenericFSID. This goes some way to addressing problem 1, described above.

File Exchange

The final part of the solution for problem 1 is the File Exchange interface for disk drivers, as defined above. To mount non-HFS partitions in an Apple partition map, File Exchange (and by extension any FSM plug-in) uses this interface in the following way.

1. It first creates a new drive queue element by cloning an existing drive queue element using kGetADrive.
2. It then retargets that drive queue element to represent the partition map for the disk using kRegisterPartition. For an Apple partition map, this is a two-step process. First it must set the partition to start at block 0 and be 2 blocks long. This gives access to the driver descriptor map (DDM) and to the first partition map entry. It then uses the first partition map entry to determine the size of the partition map. It then retargets the drive to represent the entire DDM and partition map.
3. It then reads through the partition map looking for the required partition type. For each found partition, it creates a new drive queue element (using kGetADrive) and sets that drive queue element to represent the partition's data. It can then mount a volume on that drive queue element.

A similar technique can be used for non-Apple partition maps.

File Exchange also includes a partial solution to problem 2 in that it contains a generic SCSI disk driver. At startup time, File Exchange scans the SCSI bus looking for devices that contain DOS partition maps. When it finds such a device, it loads its generic SCSI driver for the device. Obviously that driver supports the File Exchange interface, which File Exchange then uses (in a similar process to that described above) to read through the DOS partition map and create drives for all the mountable DOS partitions on the disk.

This is only a partial solution because (a) it only supports SCSI and ATA devices (the system includes a generic ATA device driver), but not any other block devices, and (b) the mechanism for loading the generic SCSI driver is not documented to developers. However, as a disk driver writer, you can craft your driver to guarantee a total solution to problem 2, as described in Cooperating with File System Manager.

Private Control and Status Requests

If you define private Control and Status requests for communication with your device driver, you must follow certain rules to ensure their reliable operation. This section outlines these rules.

Private csCode Selection

If your driver claims to supports Driver Gestalt, it must not use any csCode below 128 for a private Control or Status request. All private csCodes must be allocated from the range 128 to 32767.

Private Means Private

If you implement a Control or Status request that is private to your driver, you must issue it only to your driver. Do not issue your private Control and Status requests to other drivers, because the other driver might use the private csCode for a completely different purpose, one that is potentially fatal to user data (such as rewriting the partition map!).

At a minimum, you must check the driver name before issuing a private Control or Status request. You may also want to perform other checks (such as verifying a signature in the driver header, or issuing a private Driver Gestalt) just to be sure.

Synchronous != System Task Time

As described in DTS Technote 1067, "Traditional Device Drivers: Sync or Swim," calling a device driver synchronously does not guarantee that the driver's entry point will run at system task time. If you are defining a Control or Status request for which your driver must do something that is not interrupt safe, you must define the request to be executed immediately.

Private Requests and Virtual Memory

If your driver supports virtual memory (you can use the kdgVMOptions Driver Gestalt selector to indicate this), you must be careful to avoid fatal page faults when fielding private Control or Status requests. Specifically, your driver must not cause a page fault while it is fielding a queued (that is, synchronous or asynchronous) request.

The Virtual Memory Manager holds the entire ParamBlockRec (80 bytes) passed to all queued _Read, _Write, _Control, and _Status calls. In addition, VM holds the I/O buffer (pointed to by ioBuffer, for length ioReqCount) for _Read and _Write requests. Thus your driver can safely access this memory without causing a fatal page fault.

The problem comes when you define a private Control or Status request whose ParamBlockRec contains a pointer to another piece of memory. If your driver accesses that memory, it may cause a page fault. If your driver supports virtual memory, that page fault will be fatal (because a page fault while any paging device is busy is fatal).

There are a number of ways to avoid this problem.

1. Always include all information "inline" in the parameter block. Remember that the parameter block is automatically held for you by the Virtual Memory Manager.
2. If you must include pointers in your parameter block, define your private Control or Status interface to be called immediately. Immediate requests to a driver do not mark the driver as busy, and hence any page faults they cause will not be fatal. However, your driver must be written to support immediate requests of this kind.
3. If none of the above are suitable, you must require that your clients hold any buffers pointed to by the parameter block.

If you're making a queued Control or Status request to a device driver which supports paging and the parameter block contains pointers to other data structures, you should hold those data structures, just to be sure.

For more background about how the Mac OS Virtual Memory Manager prevents fatal page faults, see DTS Technote 1094, "Virtual Memory Application Compatibility."

Read-Verify Mode

Very few disk driver writers support read-verify mode in their drivers, perhaps on the mistaken assumption that it is difficult to do. This may be because the historical definition of read-verify mode in the ".Sony" driver is tricky to implement for any DMA-based peripheral. This section explains the current definition of read-verify mode, the best way to support it in your driver, and the best way for application software to use it.

Read-Verify Mode Explained

Read-verify mode is engaged by setting rdVerifyMask in the ioPosMode field of the I/O parameter block passed to a device driver. The original definition of read-verify mode is that the driver should do a byte-for-byte comparison of the data buffer (pointed to be ioBuffer and ioReqCount) with the data on disk. If they are the same, the operation would succeed. If they are different, the operation would fail with an ioErr.

This was easy to implement in the classic ".Sony" driver because the driver polled all bytes in to and out of memory. So implementing read-verify mode was a simple as changing the original copy loop:

while ( err == noErr && ioActCount != ioReqCount ) {
    err = GetByte(ioBuffer + ioActCount);
    if (err == noErr) {
        ioActCount += 1;
    }
}

while ( err == noErr && ioActCount != ioReqCount ) {
    err = GetByte(&tmp);
    if (err == noErr && tmp != *(ioBuffer + ioActCount)) {
        err = ioErr;
    }
    if (err == noErr) {
        ioActCount += 1;
    }
}

This form of read-verify mode is tricky to implement in modern disk drivers, which typically use a DMA engine to transfer the data. So the definition of read-verify mode has changed, as explained in the next section.

Implementing Read-Verify Mode in Your Driver

The new definition of read-verify mode is simple to explain, and to implement in your driver. If your driver gets a read-verify request, it should treat it exactly like a read request except that it must disable all caches for the request. The data transferred into memory must have originated from the physical medium itself.

This new definition of read-verify mode still allows applications to perform read-verify operations, as explained in the next section.

Using Read-Verify Mode in an Application

It is easy to write software that uses read-verify mode in way that is compatible with both the old and new definitions. The FSWriteVerify routine in the DTS sample "MoreFiles" is an excellent example. The basic algorithm is as follows.

1. Write the data to the disk in the traditional way.
2. Copy the data to a temporary buffer.
3. Read the data back into the temporary buffer.
4. Compare the temporary buffer to the original data.

This works because:

• if the driver implements read-verify mode in the old way, any errors will be detected at step 3, and
• if the driver implements read-verify mode in the new way, any errors will be detected at step 4.

Color Icons

A classic problem with disk drivers is that the mechanism for returning icons from a disk driver (Control requests kDriveIcon (21) and kMediaIcon (22), documented in Technote DV 17, "Sony Driver: What Your Sony Drives for You") is limited to black-and-white icons. In Mac OS 8, the Finder was changed to look at the drive and apply special-case color icons, but there was still no generic way for a disk driver to return a color icon.

Mac OS 8.5 and later allow disk drivers to return color icons. This is done through two new Driver Gestalt selectors, kdgPhysDriveIconSuite (equivalent to the kDriveIcon (21) Control request) and kdgMediaIconSuite (equivalent to the kMediaIcon (22) Control request). To give your drives a color icon, you must respond to these Driver Gestalt requests by putting a pointer to an icon family ('icns') in driverGestaltResponse. The icon family allows you to return any number of icon sizes and depths in one data structure.

You can build an icon family in a number of ways.

• Manually -- The format is documented in "IconServices.r". This approach is most suitable for boot disk drivers which typically statically link the icon into the driver code resource.
• Resource Editor -- Modern resource editors have been updated to edit these structures directly.
• Programatically -- The Icon Services programming interface allows you to create an icon family from an icon suite, as shown in the code sample below. This approach is more suitable for disk drivers that are loaded after the machine has started to boot, for example, network or disk image drivers.

static IconFamilyPtr GetRamDiskIconFamily(void)
{
    OSErr err;
    OSErr junk;
    IconFamilyPtr result;
    IconSuiteRef iconSuite;
    IconFamilyHandle iconFamily;
    Size iconFamilySize;
    
    result = nil;
    iconSuite = nil;
    iconFamily = nil;
    
    err = GetIconSuite(&iconSuite, 128, kSelectorAllAvailableData);
    if (err == noErr) {
        err = IconSuiteToIconFamily(iconSuite, kSelectorAllAvailableData, &iconFamily);
    }
    if (err == noErr) {
        iconFamilySize = GetHandleSize( (Handle) iconFamily);
        
        result = (IconFamilyPtr) NewPtrSys(iconFamilySize);
        err = MemError();
        if (err == noErr && result == nil) {
            err = memFullErr;
        }
    }
    if (err == noErr) {
        BlockMoveData(*iconFamily, result, iconFamilySize);
    }
     // Clean up.
     if (iconSuite != nil) {
        (void) DisposeIconSuite(iconSuite, false);      
    }
    if (iconFamily != nil) {
        DisposeHandle( (Handle) iconFamily);
    }
    
    return result;
}

IMPORTANT:
Icon Services always requests icons using an immediate request at system task time. Your driver can move or purge memory in response to these requests. Be warned; however, that this immediate request can cause your driver to be reentered.

IMPORTANT:
If an application issues these Driver Gestalt requests, it must follow Icon Services and issue them using an immediate request at system task time.

Disk Driver Power Management

This section is not yet finished and has been omitted in the interests of shipping an initial version of the technote. A future revision of this technote will cover disk driver power management. In the meantime, you can consult the following references:

• Inside Macintosh: Devices, Power Manager
• DTS Technote 1046, "Inside Macintosh: Devices, Power Manager Addenda"
• DTS Technote 1039, "File Access and the Power Manager"

Target Mode

Most PowerBooks support target mode (commonly known as "SCSI disk mode"), in which the attachment of a special cable causes the PowerBook to make its internal hard disk device available as a SCSI target device. For PowerBooks that use internal SCSI hard disk devices, support for target mode requires no special work by the disk driver. The PowerBook simply stays off of the SCSI bus and the host computer has free access to the PowerBook's internal hard disk device. However, for PowerBooks that use an internal ATA hard disk device, the implementation of target mode is somewhat more complex, and requires explicit support by the ATA disk driver.

When a PowerBook with an internal ATA hard disk device boots in target mode, the CPU runs special target mode software. This software loads the ATA driver for the internal hard disk device and then puts the built-in SCSI controller into target mode, listening for incoming SCSI requests. When such a request is made, the CPU services that request by interpreting the incoming SCSI command. If the command requires disk I/O, the CPU makes an appropriate I/O request to the ATA disk driver to satisfy that I/O.

In order to support target mode, your ATA disk driver must support some additional Control and Status requests that allow the target mode software to do its job. These requests are described in the remainder of this section.

Target Mode Checklist

If your ATA disk driver is having trouble when used in target mode, check that you support the following items.

• You must support the kdgBoot ('boot') Driver Gestalt selector as described above.
• You must return kdgDiskType ('disk') in response to the kdgDeviceType ('devt') Driver Gestalt selector.
• You must support the kPhysicalIOCode (17) Control request, described below.
• You must support the kGetDriveCapacity (125) Status request, described below.
• You must support the kSetPowerMode (70) Control request, described in Designing PCI Cards and Drivers for Power Macintosh Computers.
• You may choose to support the kGetErrorInfo (123) and kGetDriveInfo (124) Status requests, although the system will accommodate you not supporting them. See below for details of how to support these Status requests.

Required Control and Status Requests

Your ATA driver must support the Control and Status requests described in this section in order to work in target mode.

Switching to Physical I/O Mode

In response to this request, your disk driver must change how it does logical-to-physical block translation on the drive specified by ioVRefNum. If csParam[0] is 1, your driver must disable logical-to-physical block translations on the drive for subsequent I/O requests. In this mode, an I/O request for logical block X will always access physical block X. If csParam[0] is 0, your driver must re-enable logical-to-physical block translation. In this mode, an I/O request for logical block X will access physical block X + Y, where Y is the offset from the beginning of the disk of the partition represented by the drive.

For more details on logical-to-physical block translation, see Block Translation.

If ioVRefNum is not a drive number controlled by your driver, it must return nsDrvErr.

Returning Disk Size

In response to this request, your disk driver must return the physical size (in 512-byte blocks) of the disk in the device.

If ioVRefNum is not an ataDeviceID of a device controlled by your driver, it must return nsDrvErr.

Optional Status Requests

Your ATA driver may support the following Status requests to improve the fidelity of SCSI target emulation.

Returning Error Information

In response to this request, your disk driver must return the information described above about the last error that occurred on the drive.

If ioVRefNum is not a drive number controlled by your driver, it must return nsDrvErr.

Getting Information About the Drive

In response to this request, your disk driver must return the information described above about the attached drive. The target mode software uses this information to satisfy a SCSI Inquiry ($12) command.

If ioVRefNum is not an ataDeviceID of a device controlled by your driver, it must return nsDrvErr.

Summary

When the war of the giants is over, the war of the pygmies will begin.

Winston S. Churchill

This technote is the summary!

• See the Existing Information section of the technote.

Acrobat version of this Note (1900K).

Data Structure to Aid Security and Recovery Software (49K).

PartitionExtras.h (49K).

MoreIsBetter (contains MoreDisks module) (486K).